server.h: Improve documentation of mmd struct.

This adds a sentence to the description of the structure which explains
how the misc_meta_data structure is used for communication betweeen
the server process and the command handlers. The patch also contains
some minor language improvements.

diff --git a/server.h b/server.h
index 93fd558cd7636db5ee0fe6c3ded7a053ab9d3a2e..8de691ca321bd49db2d7c25398537f31b7d03a0c 100644 (file)
--- a/server.h
+++ b/server.h
@@ -34,20 +34,18 @@ struct sender_command_data {
 };
 
 /**
- * Used for parent-child communication.
+ * Miscellaneous data for communication between server and command handlers.
  *
- * There's only one struct of this type which lives in shared memory
- * for communication between the server instances. Access to this
- * area is serialized via mmd_lock() and mmd_unlock(). There are two
- * reasons for a variable to be included here:
+ * There's only one instance of this structure which lives in a shared memory
+ * area. Command handlers communicate with the server process through this
+ * area. Changes made by the command handlers stay after the command handler
+ * exits. Conversely, changes made by the server process propagate to the
+ * command handlers. Access to this area is serialized via mmd_lock() and
+ * mmd_unlock().
  *
- *     - At least one command (i.e. child of the server) must be able to
- *     change its value.
- *
- * or
- *
- *     - The contents are listed in the stat command and have to be up to
- *     date.
+ * There are two reasons for a variable to be included here: (a) at least one
+ * command handler changes its value, or (b) updates by the server must
+ * propagate to the stat command handlers.
  */
 struct misc_meta_data {
        /** The size of the current audio file in bytes. */
@@ -56,11 +54,11 @@ struct misc_meta_data {
        unsigned int vss_status_flags;
        /** The new status flags -- commands may set them. */
        unsigned int new_vss_status_flags;
-       /** The number of data chunks sent for the current audio file. */
+       /** The number of data chunks sent so far. */
        long unsigned chunks_sent;
        /** Set by the jmp/ff commands to the new position in chunks. */
        long unsigned repos_request;
-       /** The number of the chunk currently sent out. */
+       /** The number of the chunk currently being sent. */
        long unsigned current_chunk;
        /** The milliseconds that have been skipped of the current audio file. */
        long offset;
@@ -69,8 +67,8 @@ struct misc_meta_data {
        /**
         * The event counter.
         *
-        * Commands may increase this to force a status update to be sent to all
-        * connected clients.
+        * Commands may increase this to force a status update to be sent to
+        * all connected stat clients.
         */
        unsigned int events;
        /** The number of audio files already sent. */