Improve documentation of mm.c and mm.h.

This was in a rather bad shape and referred to functions like
mood_open() which have been renamed long ago.

diff --git a/mm.h b/mm.h
index 2caace7f84220c23119ccb7d1bd7140212086a6a..bc1e9f2b7b10f4a7a7bd841ed7651c17e2484afd 100644 (file)
--- a/mm.h
+++ b/mm.h
@@ -43,12 +43,8 @@ typedef int mood_parser(int, char **, void **);
 /**
  * Deallocate resources which were allocated by the mood_parser.
  *
- * This optional function of a mood_method is used to free any resources
- * allocated in mood_open() by the mood_parser. The argument passed is a
- * pointer to the mood_method specific data structure that was returned by the
- * mood_parser.
- *
- * \sa mood_parser.
+ * Function to free the resources allocated in \ref mood_method::parser. The
+ * argument is a pointer to mood method specific data returned by ->parser().
  */
 typedef void mood_cleanup_function(void *);
 

diff --git a/mood.c b/mood.c
index 9b00e619d75a75b4a6457d16b9005ffdf2e0bdf0..42f6421c93c0bdc058ca6036366375e3852cb3bb 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 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. */
@@ -524,9 +522,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
@@ -537,8 +533,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
 {
@@ -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)
 {
@@ -854,18 +847,14 @@ out:
        free(aa.array);
        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)
 {