Improve doc comments.

[disorder] / server / play.c

diff --git a/server/play.c b/server/play.c
index b9d452bb7f8ff9bc8352b708b154999c1100280e..8fd6d4cf945fcb2107f9d04bd968f4906faa1098 100644 (file)
--- a/server/play.c
+++ b/server/play.c
@@ -267,7 +267,7 @@ static const struct stringlist *find_player(const struct queue_entry *q) {
  * @return @ref START_OK, @ref START_HARDFAIL or @ref START_SOFTFAIL
  *
  * This makes @p actually start playing.  It calls prepare() if necessary and
- * either sends an @ref SM_START command or invokes the player itself in a
+ * either sends an @ref SM_PLAY command or invokes the player itself in a
  * subprocess.
  *
  * It's up to the caller to set @ref playing and @c playing->state (this might
@@ -310,7 +310,11 @@ static int start(ev_source *ev,
   }
 }
 
-/** @brief Child-process half of start() */
+/** @brief Child-process half of start()
+ * @return Process exit code
+ *
+ * Called in subprocess to execute non-raw-format players (via plugin).
+ */
 static int start_child(struct queue_entry *q, 
                        const struct pbgc_params *params,
                        void attribute((unused)) *bgdata) {
@@ -354,6 +358,9 @@ static int start_child(struct queue_entry *q,
 /** @brief Prepare a track for later play
  * @return @ref START_OK, @ref START_HARDFAIL or @ref START_SOFTFAIL
  *
+ * This can be called either when we want to play the track or slightly before
+ * so that some samples are decoded and available in a buffer.
+ *
  * Only applies to raw-format (i.e. speaker-using) players; everything else
  * gets @c START_OK.
  */
@@ -382,7 +389,15 @@ int prepare(ev_source *ev,
   return rc;
 }
 
-/** @brief Child-process half of prepare() */
+/** @brief Child-process half of prepare()
+ * @return Process exit code
+ *
+ * Called in subprocess to execute the decoder for a raw-format player.
+ *
+ * @todo We currently run the normalizer from here in a double-fork.  This is
+ * unsatisfactory for many reasons: we can't prevent it outliving the main
+ * server and we don't adequately report its exit status.
+ */
 static int prepare_child(struct queue_entry *q, 
                          const struct pbgc_params *params,
                          void attribute((unused)) *bgdata) {
@@ -643,8 +658,8 @@ void disable_random(const char *who) {
 /* Scratching --------------------------------------------------------------- */
 
 /** @brief Scratch a track
- * @param User responsible (or NULL)
- * @param Track ID (or NULL for current)
+ * @param who User responsible (or NULL)
+ * @param id Track ID (or NULL for current)
  */
 void scratch(const char *who, const char *id) {
   struct queue_entry *q;