From: Andre Noll <maan@tuebingen.mpg.de>
Date: Thu, 19 May 2022 16:58:53 +0000 (+0200)
Subject: mood.c: Improve documentation of reload_current_mood().
X-Git-Tag: v0.7.1~15
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=ff4398ca3e0c1d3d9327a9d75a979e19187204c8;p=paraslash.git

mood.c: Improve documentation of reload_current_mood().

The old text was a bit clumsy and too short.
---

diff --git a/mood.c b/mood.c
index a228b243..b3f007b6 100644
--- a/mood.c
+++ b/mood.c
@@ -715,9 +715,17 @@ static int reload_current_mood(void)
  * \param pb Unused.
  * \param data Its type depends on the event.
  *
- * This function performs actions required due to the occurrence of the given
- * event. Possible actions include reload of the current mood and update of the
- * score of an audio file.
+ * This function updates the score table according to the event that has
+ * occurred. Two actions are possible: (a) reload the current mood, or (b)
+ * add/remove/update the row of the score table which corresponds to the audio
+ * file that has been modified or whose afs info has been changed. It depends
+ * on the type of the event which action (if any) is performed.
+ *
+ * The callbacks of command handlers such as com_add() or com_touch() which
+ * modify the audio file table call this function. The virtual streaming system
+ * also calls this after it has updated the afs info of the file it is about to
+ * stream (the one with the highest score). If the file stays admissible, its
+ * score is recomputed so that a different file is picked next time.
  *
  * \return Standard.
  */