From 591b16bbe13ca336c4cef00e8f9f808c1bb4c9a0 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sat, 22 Nov 2008 22:36:22 +0100
Subject: [PATCH 1/1] Minor documentation improvements.

---
 afh.c         |  8 ++++++++
 blob.c        |  2 +-
 filter.h      |  1 +
 mood.c        |  2 +-
 send.h        |  2 +-
 send_common.c | 10 ++++++++++
 time.c        | 10 ++++++++++
 write.c       |  1 +
 8 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/afh.c b/afh.c
index 454517f4..86322422 100644
--- a/afh.c
+++ b/afh.c
@@ -120,6 +120,14 @@ static int cat_file(void *audio_file_data, struct afh_info *afhi)
 	return 1;
 }
 
+/**
+ * The main function of para_afh.
+ *
+ * \param argc Usual argument count.
+ * \param argv Usual argument vector.
+ *
+ * \return \p EXIT_FAILURE or \p EXIT_SUCCESS.
+ */
 int main(int argc, char **argv)
 {
 	int ret, audio_format_num, fd;
diff --git a/blob.c b/blob.c
index cdad8d7f..fd8ddc80 100644
--- a/blob.c
+++ b/blob.c
@@ -55,7 +55,7 @@ enum blob_ls_flags {
 
 /** Structure passed to the \p print_blob function. */
 struct lsblob_action_data {
-	/* The flags given at the command line. */
+	/** The flags given at the command line. */
 	uint32_t flags;
 	/** Message buffer. */
 	struct para_buffer pb;
diff --git a/filter.h b/filter.h
index 500a8537..8c1c9e0d 100644
--- a/filter.h
+++ b/filter.h
@@ -34,6 +34,7 @@ struct filter_node {
 
 /** Describes one running instance of a chain of filters */
 struct filter_chain {
+	/** The length of the filter chain. */
 	unsigned int num_filters;
 	/**
 	 * The number of channels of the current stream.
diff --git a/mood.c b/mood.c
index aa220f1e..cdc0745a 100644
--- a/mood.c
+++ b/mood.c
@@ -84,7 +84,7 @@ typedef void mood_cleanup_function(void *);
  * Used for scoring and to determine whether a file is admissible.
  */
 struct mood_method {
-	/* The name of the method. */
+	/** The name of the method. */
 	const char *name;
 	/** Pointer to the mood parser. */
 	mood_parser *parser;
diff --git a/send.h b/send.h
index 270affd5..2fe1cc56 100644
--- a/send.h
+++ b/send.h
@@ -107,7 +107,7 @@ struct sender_client {
 
 /** Describes the current status of one paraslash sender. */
 struct sender_status {
-	/* The file descriptor of the socket this sender is listening on. */
+	/** The file descriptor of the socket this sender is listening on. */
 	int listen_fd;
 	/** The TCP/DCCP port used by this sender. */
 	int port;
diff --git a/send_common.c b/send_common.c
index c0098b98..3d870088 100644
--- a/send_common.c
+++ b/send_common.c
@@ -62,6 +62,8 @@ static int open_sender(unsigned l4type, int port)
  * Close the file descriptor given by \a sc, remove it from the close-on-fork
  * list, destroy the chunk queue of this client, delete the client from the
  * list of connected clients and free the sender_client struct.
+ *
+ * \sa shutdown_clients().
  */
 void shutdown_client(struct sender_client *sc, struct sender_status *ss)
 {
@@ -76,6 +78,14 @@ void shutdown_client(struct sender_client *sc, struct sender_status *ss)
 	ss->num_clients--;
 }
 
+/**
+ * Shut down all clients connected to a paraslash sender.
+ *
+ * \param ss The sender whose clients are to be shut down.
+ *
+ * This just loops over all connected clients and calls shutdown_client()
+ * for each client.
+ */
 void shutdown_clients(struct sender_status *ss)
 {
 	struct sender_client *sc, *tmp;
diff --git a/time.c b/time.c
index 1fd7b098..0ebc6ec0 100644
--- a/time.c
+++ b/time.c
@@ -170,6 +170,16 @@ int tv_convex_combination(const long a, const struct timeval *tv1,
 	return ret;
 }
 
+/**
+ * Compute when to send a chunk of an audio file.
+ *
+ * \param chunk_num The number of the chunk.
+ * \param chunk_tv The duration of one chunk.
+ * \param stream_start When the first chunk was sent.
+ * \param result The time when to send chunk number \a chunk_num.
+ *
+ * This function computes stream_start + chunk_num * chunk_time.
+ */
 void compute_chunk_time(long unsigned chunk_num,
 		struct timeval *chunk_tv, struct timeval *stream_start,
 		struct timeval *result)
diff --git a/write.c b/write.c
index 140e80e5..78e48dcd 100644
--- a/write.c
+++ b/write.c
@@ -34,6 +34,7 @@ struct check_wav_task {
 	unsigned channels;
 	/** Sample rate specified in wav header given by \a buf. */
 	unsigned samplerate;
+	/** The task structure used by the scheduler. */
 	struct task task;
 };
 
-- 
2.39.2