From fa9122a948ce06248fda918ed9c8d4827b61c4bf Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@tuebingen.mpg.de>
Date: Sun, 21 May 2017 21:44:45 +0200
Subject: [PATCH] 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.
---
 mm.h   |  8 ++------
 mood.c | 35 ++++++++++++-----------------------
 2 files changed, 14 insertions(+), 29 deletions(-)

diff --git a/mm.h b/mm.h
index 2caace7f..bc1e9f2b 100644
--- 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 9b00e619..42f6421c 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 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)
 {
-- 
2.39.2