Add some missing documentation of public functions.

diff --git a/afh_common.c b/afh_common.c
index 1005139d8365165903ac01b8dac011017346c5c9..c866b4388ab14ac7880e8bcdf4c9bb0a56cf3306 100644 (file)
--- a/afh_common.c
+++ b/afh_common.c
@@ -236,6 +236,13 @@ void afh_get_chunk(long unsigned chunk_num, struct afh_info *afhi,
        *len = afhi->chunk_table[chunk_num + 1] - pos;
 }
 
+/**
+ * Compute the size of the largest chunk of an audio file.
+ *
+ * \param afhi The audio format handler struct containing the chunk table.
+ *
+ * \return The number of bytes of the largest chunk.
+ */
 uint32_t afh_get_largest_chunk_size(struct afh_info *afhi)
 {
        uint32_t n, largest = 0, *ct = afhi->chunk_table;

diff --git a/afs.c b/afs.c
index 1350db3423c3a184cb645e09cae9a2ebb060358b..b83fa23d87b1cd75ad971b2056a6a88ef39c9c65 100644 (file)
--- a/afs.c
+++ b/afs.c
@@ -1151,12 +1151,30 @@ void afs_event(enum afs_events event, struct para_buffer *pb,
        }
 }
 
+/**
+ * Dummy event handler for the images table.
+ *
+ * \param event Unused.
+ * \param pb Unused.
+ * \param data Unused.
+ *
+ * This table does not honor events.
+ */
 int images_event_handler(__a_unused enum afs_events event,
        __a_unused  struct para_buffer *pb, __a_unused void *data)
 {
        return 1;
 }
 
+/**
+ * Dummy event handler for the lyrics table.
+ *
+ * \param event Unused.
+ * \param pb Unused.
+ * \param data Unused.
+ *
+ * This table does not honor events.
+ */
 int lyrics_event_handler(__a_unused enum afs_events event,
        __a_unused struct para_buffer *pb, __a_unused void *data)
 {

diff --git a/aft.c b/aft.c
index 103373493f8cdadc8a6c5a640041f7453ef1fc30..9a22fe81d67006992d5dbb7e775bc37bbc68e094 100644 (file)
--- a/aft.c
+++ b/aft.c
@@ -2458,6 +2458,18 @@ static void afs_stat_callback(int fd, const struct osl_object *query)
        pass_buffer_as_shm(buf, strlen(buf), &fd);
 }
 
+/**
+ * Get the current afs status items from the afs process and send it using RC4.
+ *
+ * \param rc4c The rc4 context for data encryption.
+ * \param parser_friendly Whether parser-friendly output format should be used.
+ *
+ * As the contents of the afs status items change in time and the command
+ * handler only has a COW version created at fork time, it can not send
+ * up-to-date afs status items directly. Therefore the usual callback mechanism
+ * is used to pass the status items from the afs process to the command handler
+ * via a shared memory area and a pipe.
+ */
 int send_afs_status(struct rc4_context *rc4c, int parser_friendly)
 {
        struct osl_object query = {.data = &parser_friendly,

diff --git a/audiod.c b/audiod.c
index 72276ffe072f1a24fa67ac866e18c4d9a33889cd..dd6022889280eb6b19980ccdb0750af1306401fc 100644 (file)
--- a/audiod.c
+++ b/audiod.c
@@ -160,8 +160,9 @@ struct command_task {
 #define FOR_EACH_AUDIO_FORMAT(af) for (af = 0; af < NUM_AUDIO_FORMATS; af++)
 
 /**
- * get the audio format number
- * \param name the name of the audio format
+ * Get the audio format number.
+ *
+ * \param name The name of the audio format.
  *
  * \return The audio format number on success, -E_UNSUPPORTED_AUDIO_FORMAT if
  * \a name is not a supported audio format.
@@ -178,6 +179,27 @@ int get_audio_format_num(const char *name)
        return -E_UNSUPPORTED_AUDIO_FORMAT;
 }
 
+/**
+ * Compute the play time based on information of the given slot.
+ *
+ * \param slot_num The slot number (negative means: no slot).
+ *
+ * This computes a string of the form "0:07 [3:33] (3%/3:40)" using information
+ * from the status items received from para_server and the start time of the
+ * (first) writer of the given slot.
+ *
+ * It has to to take into account that probably the stream was not started at
+ * the beginning of the file, that the clock between the server and the client
+ * host may differ and that playback of the stream was delayed, e.g. because
+ * the prebuffer filter is used in the filter chain of the given slot.
+ *
+ * If no writer is active in the given slot, or \a slot_num is negative
+ * (indicating that para_audiod runs in standby mode), an approximation based
+ * only on the status items is computed and the returned string is prefixed
+ * with "~".
+ *
+ * \return A string that must be freed by the caller.
+ */
 char *get_time_string(int slot_num)
 {
        int ret, seconds = 0, length;
@@ -580,6 +602,15 @@ static int receiver_running(int format)
        return ret;
 }
 
+/**
+ * Return the root node of the current buffer tree.
+ *
+ * This is only used for stream grabbing.
+ *
+ * \return \p NULL if no slot is currently active. If more than one buffer tree
+ * exists, the node corresponding to the most recently started receiver is
+ * returned.
+ */
 struct btr_node *audiod_get_btr_root(void)
 {
        int i, newest_slot = -1;