From 16af9d479765f9ea4b981533116d1d030285cd68 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Thu, 4 Apr 2013 17:00:01 +0000
Subject: [PATCH] Add documentation of public functions in check_wav.c.

The init, shutdown, pre_select and post_select functions of this
file are exported via check_wav.h, so they should be documented. This
commit adds doxygen comments for all of them.
---
 check_wav.c | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/check_wav.c b/check_wav.c
index 80265472..872a7d0a 100644
--- a/check_wav.c
+++ b/check_wav.c
@@ -19,9 +19,13 @@
 /** Length of a standard wav header. */
 #define WAV_HEADER_LEN 44
 
+/** The possible states of a check_wav instance. */
 enum check_wav_state {
+	/** Initial state, less than \p WAV_HEADER_LEN bytes available. */
 	CWS_NEED_HEADER,
+	/** Wav hader was detected. */
 	CWS_HAVE_HEADER,
+	/** First part of the stream did not look like a wav header. */
 	CWS_NO_HEADER,
 };
 
@@ -37,6 +41,15 @@ struct check_wav_context {
 	unsigned sample_rate;
 };
 
+/**
+ * Set select timeout according to the given context.
+ *
+ * \param s Contains the timeval that should be set.
+ * \param cwc Contains a pointer to the buffer tree node.
+ *
+ * This requests a minimal timeout from the scheduler if btrn of \a cwc is not
+ * idle.
+ */
 void check_wav_pre_select(struct sched *s, struct check_wav_context *cwc)
 {
 	int ret = btr_node_status(cwc->btrn, cwc->min_iqs, BTR_NT_INTERNAL);
@@ -95,6 +108,22 @@ out:
 	return 1;
 }
 
+/**
+ * Filter out the wav header, pushdown everything else.
+ *
+ * \param cwc The context of this instance.
+ *
+ * This function looks at the first \p WAV_HEADER_SIZE bytes of the input queue
+ * of the btrn of \a cwc. If they look like a wav header, the function extracts
+ * the information of interest and swallows this part of the stream. Otherwise
+ * it is pushed down to all children of \a btrn. In either case the rest of the
+ * input is pushed down as well.
+ *
+ * Once the first part has been processed this way, the state of the instance
+ * changes from \p CWS_NEED_HEADER to \p CWS_HAVE_HEADER or \p CWS_NO_HEADER.
+ *
+ * \return Standard.
+ */
 int check_wav_post_select(struct check_wav_context *cwc)
 {
 	struct btr_node *btrn = cwc->btrn;
@@ -160,6 +189,23 @@ out:
 	return ret;
 }
 
+/**
+ * Allocate and set up a new check_wav instance.
+ *
+ * \param parent This buffer tree node will be the parent of the new node.
+ * \param child The child of the new node.
+ * \param params Default values and options.
+ * \param cw_btrn A pointer to the check wav node is returned here.
+ *
+ * This function also sets up the ->execute handler of the btrn so that all
+ * children of this node can figure out channel count, sample rate, etc.
+ *
+ * \return The (opaque) handle of the newly created check_wav instance. It is
+ * supposed to be passed to \ref check_wav_pre_select() and \ref
+ * check_wav_post_select().
+ *
+ * \sa \ref btr_new_node.
+ */
 struct check_wav_context *check_wav_init(struct btr_node *parent,
 		struct btr_node *child, struct wav_params *params,
 		struct btr_node **cw_btrn)
@@ -177,6 +223,14 @@ struct check_wav_context *check_wav_init(struct btr_node *parent,
 	return cwc;
 }
 
+/**
+ * Dellocate all ressources of a check_wav instance.
+ *
+ * \param cwc Determines the instance to shut down.
+ *
+ * This function may only be called after check_wav_post_select() has returned
+ * negative.
+ */
 void check_wav_shutdown(struct check_wav_context *cwc)
 {
 	free(cwc);
-- 
2.39.5