Improve documentation of mood.c.

This dedoxifies and improves the comments of the three structures declared
in this file and also streamlines the documentation of compute_score(),
removing the pointless example and stating more clearly that the normalization
factors are designed to even out the two contributions of the score of the
hypothetical file.

1 files changed, 28 insertions, 36 deletions

diff --git a/mood.c b/mood.c
index 9983c08e..2023fa39 100644
--- a/mood.c
+++ b/mood.c
@@ -21,52 +21,51 @@ int mp_init(const char *definition, int nbytes, struct mp_context **result,
 bool mp_eval_row(const struct osl_row *aft_row, struct mp_context *ctx);
 void mp_shutdown(struct mp_context *ctx);
 
-/**
- * Contains statistical data of the currently admissible audio files.
- *
- * It is used to assign normalized score values to each admissible audio file.
+/*
+ * Statistics about the set of admissible audio files. Computed at mood
+ * load time. The values are used to assign normalized score values to
+ * each admissible audio file. The statistics of the current mood are
+ * also accessed when the score of an audio file needs to be recomputed,
+ * for example because it was streamed or because the file's metadata got
+ * modified via the touch subcommand.
  */
 struct afs_statistics {
-	/** Sum of num played over all admissible files. */
+	/* Sum of the num_played counts of the admissible files. */
 	int64_t num_played_sum;
-	/** Sum of last played times over all admissible files. */
+	/* Same, but with the last_played values. */
 	int64_t last_played_sum;
-	/** Quadratic deviation of num played count. */
+	/* Quadratic deviation of num_played count. */
 	int64_t num_played_qd;
-	/** Quadratic deviation of last played time. */
+	/* Same but with last played time. */
 	int64_t last_played_qd;
-	/** Correction factor for the num played score. */
+	/* Correction factor for the num played score. */
 	int64_t num_played_correction;
-	/** Correction factor for the last played score. */
+	/* Correction factor for the last played score. */
 	int64_t last_played_correction;
-	/** Common divisor of the correction factors. */
+	/* Common divisor of the correction factors. */
 	int64_t normalization_divisor;
-	/** Number of admissible files */
+	/* Number of admissible files */
 	unsigned num;
 };
 
-/**
- * Stores an instance of a loaded mood (parser and statistics).
- *
- * A structure of this type is allocated and initialized when a mood is loaded.
+/*
+ * Represents a loaded mood. Contains the context of the bison mood parser
+ * and the statistics. Allocated and initialized at mood load time.
  */
 struct mood_instance {
-	/** NULL means that this is the "dummy" mood. */
+	/* NULL means that this is the "dummy" mood. */
 	char *name;
-	/** Bison's abstract syntax tree, used to determine admissibility. */
+	/* Bison's abstract syntax tree, used to determine admissibility. */
 	struct mp_context *parser_context;
-	/** To compute the score. */
+	/* To compute the score. */
 	struct afs_statistics stats;
-	/** NULL means to operate on the global score table. */
+	/* NULL means to operate on the global score table. */
 	struct osl_table *score_table;
 };
 
 /*
  * If current_mood is NULL then no mood is currently loaded. If
  * current_mood->name is NULL, the current mood is the dummy mood.
- *
- * The statistics are adjusted dynamically through this pointer as files are
- * added, removed or played.
  */
 static struct mood_instance *current_mood;
 
@@ -234,19 +233,12 @@ int mood_check_callback(struct afs_callback_arg *aca)
  *	nn =  mean_n / sigma_n =: hn > 0
  *	nl = -(now - mean_l) / sigma_l =: hl < 0
  *
- * We design the score function so that both contributions get the same
- * weight. Define the np and lp score of an arbitrary file as
+ * We design the score function so that for this hypothetical file both
+ * contributions get the same weight. Define the np and lp score of an
+ * arbitrary file as
  *
  *	sn := nn * -hl and sl := nl * hn
  *
- * Example:
- *	num_played mean/sigma: 87/14
- *	last_played mean/sigma: 45/32 days
- *
- *	We have hn = 87 / 14 = 6.21 and hl = -45 / 32 = -1.41. Multiplying
- *	nn of every file with the correction factor 1.41 and nl with
- *	6.21 makes the weight of the two contributions equal.
- *
  * The total score s := sn + sl has the representation
  *
  *	s = -cn * (np - mean_n) - cl * (lp - mean_l)
@@ -327,11 +319,11 @@ static int add_afs_statistics(const struct osl_row *row,
  * since the score depends on the statistics. Finally, the array is freed.
  */
 struct admissible_array {
-	/** Files are admissible wrt. this mood. */
+	/* Files are admissible wrt. this mood. */
 	struct mood_instance *m;
-	/** The size of the array */
+	/* The size of the array */
 	unsigned size;
-	/** Pointer to the array of admissible files. */
+	/* Pointer to the array of admissible files. */
 	struct osl_row **array;
 };