Improve doc comments.

[disorder] / server / play.c

diff --git a/server/play.c b/server/play.c
index 303090107e4cf400f17bc7f894355366b457c273..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) {
@@ -583,7 +598,7 @@ void play(ev_source *ev) {
     }
     /* It's become the playing track */
     playing = q;
-    time(&playing->played);
+    xtime(&playing->played);
     playing->state = playing_started;
     notify_play(playing->track, playing->submitter);
     eventlog("playing", playing->track,
@@ -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;
@@ -685,7 +700,7 @@ void scratch(const char *who, const char *id) {
       q = queue_add(config->scratch.s[r], who, WHERE_START, origin_scratch);
     }
     notify_scratch(playing->track, playing->submitter, who,
-                  time(0) - playing->played);
+                  xtime(0) - playing->played);
   }
 }
 
@@ -735,7 +750,7 @@ int pause_playing(const char *who) {
       error(0, "player indicates it cannot pause");
       return -1;
     }
-    time(&playing->lastpaused);
+    xtime(&playing->lastpaused);
     playing->uptopause = played;
     playing->lastresumed = 0;
     break;
@@ -763,13 +778,13 @@ void resume_playing(const char *who) {
   if(!playing) return;
   switch(playing->type & DISORDER_PLAYER_TYPEMASK) {
   case DISORDER_PLAYER_STANDALONE:
-    if(!playing->type & DISORDER_PLAYER_PAUSES) {
+    if(!(playing->type & DISORDER_PLAYER_PAUSES)) {
     default:
       /* Shouldn't happen */
       return;
     }
     play_resume(playing->pl, playing->data);
-    time(&playing->lastresumed);
+    xtime(&playing->lastresumed);
     break;
   case DISORDER_PLAYER_RAW:
     memset(&sm, 0, sizeof sm);