X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=mood.c;h=315ef0cbdc61b7de1a3bbbd8f8683d7ab81d9c81;hp=2b063cfd6b804373fb8f623b377781d949e53acf;hb=6811b2f8ea8b7a8c77046285c9432aee6327da80;hpb=5ba99bfbb7ec52efd4f2af8840ba7e5f8eabaa83

diff --git a/mood.c b/mood.c
index 2b063cfd..315ef0cb 100644
--- a/mood.c
+++ b/mood.c
@@ -59,15 +59,13 @@ struct mood_item {
 	struct list_head mood_item_node;
 };
 
-/**
- * Created from the mood definition by mood_open().
+/*
+ * Created from the mood definition by \ref change_current_mood().
  *
  * When a mood is opened, each line of its definition is investigated, and a
- * corresponding mood item is produced. Each mood line starts with \p accept,
- * \p deny, or \p score which determines the type of the mood line.  For each
- * such type a linked list is maintained whose entries are the mood items.
- *
- * \sa mood_item, mood_open().
+ * corresponding mood item is produced. Each mood line starts with accept,
+ * deny, or score which determines the type of the mood line. For each such
+ * type a linked list is maintained whose entries are the mood items.
  */
 struct mood {
 	/** The name of this mood. */
@@ -82,7 +80,7 @@ struct mood {
 
 /*
  * If current_mood is NULL then no mood is currently open. If
- * current_mood->name is NULL, the dummy mood is currently open
+ * current_mood->name is NULL, the dummy mood is currently open.
  */
 static struct mood *current_mood;
 
@@ -142,8 +140,8 @@ static bool get_item_score(struct mood_item *item, const struct afs_info *afsi,
 }
 
 /* returns 1 if row admissible, 0 if not, negative on errors */
-static int compute_mood_score(const struct osl_row *aft_row, struct mood *m,
-		long *result)
+static int row_is_admissible(const struct osl_row *aft_row, struct mood *m,
+		long *scorep)
 {
 	struct mood_item *item;
 	int ret;
@@ -192,7 +190,7 @@ static int compute_mood_score(const struct osl_row *aft_row, struct mood *m,
 	}
 	if (score_arg_sum)
 		score /= score_arg_sum;
-	*result = score;
+	*scorep = score;
 	return 1;
 }
 
@@ -523,9 +521,7 @@ static int del_afs_statistics(const struct osl_row *row)
 	return 1;
 }
 
-/**
- * Structure used during mood_open().
- *
+/*
  * At mood open time we determine the set of admissible files for the given
  * mood. The mood score of each admissible file is computed by adding up all
  * mood item scores. Next, we update the afs statistics and append a struct
@@ -536,8 +532,6 @@ static int del_afs_statistics(const struct osl_row *row)
  * the afs_statistics and the current time) to the mood score. Finally, all
  * audio files in the temporary array are added to the score table and the
  * array is freed.
- *
- * \sa mood_method, admissible_array.
  */
 struct admissible_file_info
 {
@@ -571,7 +565,7 @@ static int add_if_admissible(struct osl_row *aft_row, void *data)
 	int ret;
 	long score = 0;
 
-	ret = compute_mood_score(aft_row, aa->m, &score);
+	ret = row_is_admissible(aft_row, aa->m, &score);
 	if (ret <= 0)
 		return ret;
 	if (statistics.num >= aa->size) {
@@ -679,7 +673,7 @@ static int delete_from_statistics_and_score_table(const struct osl_row *aft_row)
  *
  * \return Positive on success, negative on errors.
  *
- * \sa score_delete().
+ * \sa \ref score_delete().
  */
 static int mood_delete_audio_file(const struct osl_row *aft_row)
 {
@@ -718,7 +712,7 @@ static int mood_update_audio_file(const struct osl_row *aft_row,
 	if (ret < 0)
 		return ret;
 	was_admissible = ret;
-	ret = compute_mood_score(aft_row, current_mood, &score);
+	ret = row_is_admissible(aft_row, current_mood, &score);
 	if (ret < 0)
 		return ret;
 	is_admissible = (ret > 0);
@@ -782,8 +776,7 @@ static void log_statistics(void)
 /**
  * Close the current mood.
  *
- * Free all resources of the current mood which were allocated during
- * mood_open().
+ * Frees all resources of the current mood.
  */
 void close_current_mood(void)
 {
@@ -805,8 +798,7 @@ void close_current_mood(void)
  * \return Positive on success, negative on errors. Loading the dummy mood
  * always succeeds.
  *
- * \sa struct admissible_file_info, struct admissible_array, struct
- * afs_info::last_played, mood_close().
+ * \sa struct \ref afs_info::last_played.
  */
 int change_current_mood(const char *mood_name)
 {
@@ -855,18 +847,14 @@ out:
 	return ret;
 }
 
-/**
+/*
  * Close and re-open the current mood.
  *
- * This function is used if changes to the audio file table or the
- * attribute table were made that render the current list of admissible
- * files useless. For example, if an attribute is removed from the
- * attribute table, this function is called.
- *
- * \return Positive on success, negative on errors. If no mood is currently
- * open, the function returns success.
+ * This function is called on events which render the current list of
+ * admissible files useless, for example if an attribute is removed from the
+ * attribute table.
  *
- * \sa mood_open(), mood_close().
+ * If no mood is currently open, the function returns success.
  */
 static int reload_current_mood(void)
 {