Merge branch 'refs/heads/t/doxygen'
[paraslash.git] / mood.c
diff --git a/mood.c b/mood.c
index 208bdc4..315ef0c 100644 (file)
--- 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;
 
@@ -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
 {
@@ -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)
 {
@@ -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)
 {