From: Andre Noll <maan@systemlinux.org>
Date: Sun, 21 Feb 2010 20:32:06 +0000 (+0100)
Subject: Add some missing documentation of public functions.
X-Git-Tag: v0.4.2~45
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=50fac71430f5993560d40eb5044d45d8255d7ca6;p=paraslash.git

Add some missing documentation of public functions.
---

diff --git a/afh_common.c b/afh_common.c
index 1005139d..c866b438 100644
--- 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 1350db34..b83fa23d 100644
--- 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 10337349..9a22fe81 100644
--- 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 72276ffe..dd602288 100644
--- 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;