doxygen: Add some missing documentation.
authorAndre Noll <maan@systemlinux.org>
Fri, 22 Apr 2011 16:03:28 +0000 (18:03 +0200)
committerAndre Noll <maan@systemlinux.org>
Sun, 15 May 2011 07:58:03 +0000 (09:58 +0200)
aac_common.c
buffer_tree.c
filter.h
filter_common.c
para.h
recv.h
recv_common.c
ringbuffer.c
write.h
write_common.c

index 14662fd..9e46a77 100644 (file)
@@ -15,8 +15,9 @@
 #include "error.h"
 
 /**
- * get a new libfaad decoder handle
+ * Get a new libfaad decoder handle.
  *
+ * \return The handle returned by NeAACDecOpen().
  */
 NeAACDecHandle aac_open(void)
 {
index 0e460dd..88fb836 100644 (file)
@@ -257,6 +257,8 @@ static void btr_pool_deallocate(struct btr_pool *btrp, size_t size)
  *
  * \param bnd Specifies how to create the new node.
  *
+ * \return A pointer to the newly allocated node.
+ *
  * This function always succeeds (or calls exit()). The returned pointer must
  * be freed using btr_free_node() after the node has been removed from the
  * buffer tree via btr_remove_node().
@@ -660,6 +662,11 @@ void btr_consume(struct btr_node *btrn, size_t numbytes)
        return btr_consume(btrn, sz);
 }
 
+/**
+ * Clear the input queue of a buffer tree node.
+ *
+ * \param btrn The node whose input queue should be cleared.
+ */
 void btr_drain(struct btr_node *btrn)
 {
        struct btr_buffer_reference *br, *tmp;
@@ -771,8 +778,8 @@ void btr_splice_out_node(struct btr_node *btrn)
  *
  * \param btrn The node whose output queue size should be computed.
  *
- * This function iterates over all children of the given node and returns the
- * size of the largest input queue.
+ * \return This function iterates over all children of the given node and
+ * returns the size of the largest input queue.
  */
 size_t btr_get_output_queue_size(struct btr_node *btrn)
 {
@@ -827,8 +834,9 @@ int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result)
 /**
  * Obtain the context of a buffer node tree.
  *
- * The returned pointer equals the context pointer used at creation time of the
- * node.
+ * \param btrn The node whose output queue size should be computed.
+ *
+ * \return A pointer to the \a context address specified at node creation time.
  *
  * \sa btr_new_node(), struct \ref btr_node_description.
  */
index 0808059..94657a7 100644 (file)
--- a/filter.h
+++ b/filter.h
@@ -24,8 +24,11 @@ struct filter_node {
        struct list_head callbacks;
        /** A pointer to the configuration of this instance. */
        void *conf;
+       /** The buffer tree node. */
        struct btr_node *btrn;
+       /** The task corresponding to this filter node. */
        struct task task;
+       /** The minimal input queue size, see \ref btr_node_status(). */
        size_t min_iqs;
 };
 
@@ -136,6 +139,7 @@ static inline void write_int16_host_endian(char *buf, int val)
 
 DECLARE_FILTER_INITS
 
+/** Iterate over the array of supported filters. */
 #define FOR_EACH_SUPPORTED_FILTER(j)  for (j = 0; j < NUM_SUPPORTED_FILTERS; j++)
 
 /** The filter array, one structure for each supported filter. */
index 566d97e..4b1a45d 100644 (file)
@@ -108,6 +108,11 @@ int check_filter_arg(char *fa, void **conf)
        return -E_UNSUPPORTED_FILTER;
 }
 
+/**
+ * Print help text of each filter to stdout.
+ *
+ * \param detailed If non-zero, print detailed help.
+ */
 void print_filter_helps(int detailed)
 {
        int i;
@@ -127,6 +132,17 @@ void print_filter_helps(int detailed)
        }
 }
 
+/**
+ * Set select timeout of the the scheduler.
+ *
+ * \param s The scheduler.
+ * \param t The task struct of this filter.
+ *
+ * This looks at the status of the btr node of the filter. If data is available
+ * in the input queue of the filter, or if an error occured, a minimal timeout
+ * for the next select call is requested from the scheduler. Otherwise the
+ * scheduler timeout is left unchanged.
+ */
 void generic_filter_pre_select(struct sched *s, struct task *t)
 {
        struct filter_node *fn = container_of(t, struct filter_node, task);
diff --git a/para.h b/para.h
index 7217486..5dc3912 100644 (file)
--- a/para.h
+++ b/para.h
@@ -176,7 +176,7 @@ _static_inline_ long int para_random(unsigned max)
  */
 #define EXPR_BUILD_ASSERT(cond) (sizeof(char [1 - 2 * !(cond)]) - 1)
 
-/* &a[0] degrades to a pointer: a different type from an array */
+/** &a[0] degrades to a pointer: a different type from an array */
 #define _array_size_chk(arr) EXPR_BUILD_ASSERT(\
        !__builtin_types_compatible_p(typeof(arr), typeof(&(arr)[0])))
 /** Get the size of an array */
@@ -200,6 +200,7 @@ _static_inline_ long int para_random(unsigned max)
 /** Data that indicates an eof-condition for a fec-encoded stream. */
 #define FEC_EOF_PACKET "\xec\x0d\xcc\xfe\0\0\0\0" \
        "\0\0\0\0\0\0\0\0" "\0\0\0\0\0\0\0\0" "\0\0\0\0\0\0\0\0"
+/** The number of bytes of the \a FEC_EOF_PACKET. */
 #define FEC_EOF_PACKET_LEN 32
 
 /** Used to avoid a shortcoming in vim's syntax highlighting. */
@@ -228,10 +229,12 @@ _static_inline_ long int para_random(unsigned max)
        SAMPLE_FORMAT(SF_U16_LE, "16 bit unsigned, little endian"), \
        SAMPLE_FORMAT(SF_U16_BE, "16 bit unsigned, big endian"), \
 
+/** \cond */
 #define SAMPLE_FORMAT(a, b) a
 enum sample_format {SAMPLE_FORMATS};
 #undef SAMPLE_FORMAT
 #define SAMPLE_FORMAT(a, b) b
+/** \endcond */
 
 /** Debug loglevel, gets really noisy. */
 #define LL_DEBUG 0
diff --git a/recv.h b/recv.h
index 05c5ed7..ee8138f 100644 (file)
--- a/recv.h
+++ b/recv.h
@@ -50,6 +50,12 @@ struct receiver {
         * \a argc and \a argv.
         */
        void *(*parse_config)(int argc, char **argv);
+       /**
+        * Deallocate the configuration structure of a receiver node.
+        *
+        * This calls the receiver-specific cleanup function generated by
+        * gengetopt.
+        */
        void (*free_config)(void *conf);
        /**
         * Open one instance of the receiver.
index 3fe2a13..f38184b 100644 (file)
@@ -123,6 +123,18 @@ void print_receiver_helps(int detailed)
        }
 }
 
+/**
+ * Simple pre-select hook, used by all receivers.
+ *
+ * \param s Scheduler info.
+ * \param t Determines the receiver node.
+ *
+ * This requests a minimal delay from the scheduler if the status of the buffer
+ * tree node indicates an error/eof condition. No file descriptors are added to
+ * the fd sets of \a s.
+ *
+ * \return Standard.
+ */
 int generic_recv_pre_select(struct sched *s, struct task *t)
 {
        struct receiver_node *rn = container_of(t, struct receiver_node, task);
index bf990b0..15d767e 100644 (file)
@@ -96,7 +96,7 @@ void *ringbuffer_get(struct ringbuffer *rb, int num)
  *
  * \param rb The ringbuffer identifier
  *
- * This function always succeeds and never returns a number greater than the
+ * \return This function always succeeds. It returns a number less than the
  * size of the ring buffer.
  */
 unsigned ringbuffer_filled(struct ringbuffer *rb)
diff --git a/write.h b/write.h
index 0044ae4..8a60294 100644 (file)
--- a/write.h
+++ b/write.h
@@ -19,8 +19,11 @@ struct writer_node {
        void *private_data;
        /** The writer-specific configuration of this node. */
        void *conf;
+       /** The buffer tree node associated with this writer node. */
        struct btr_node *btrn;
+       /** The task of this writer node. */
        struct task task;
+       /** The minimal input queue size (size of one audio sample). */
        size_t min_iqs;
 };
 
@@ -70,12 +73,19 @@ struct writer {
         */
        void (*close)(struct writer_node *);
        /**
-        * Shutdown the writer
+        * Shutdown the writer.
         *
         * This is a optional function pointer used for cleaning up.
         */
        void (*shutdown)(struct writer_node *);
+       /** The short and the log help text of this writer. */
        struct ggo_help help;
+       /**
+        * The callback handler.
+        *
+        * Each writer may provide an ->execute callback which can be used for
+        * inter-node communication.
+        */
        btr_command_handler execute;
 };
 
index 5988faf..faf2074 100644 (file)
@@ -35,10 +35,10 @@ void writer_init(void)
                writers[i].init(&writers[i]);
 }
 /**
- * check if given string is a valid command line for any writer
+ * Check if given string is a valid command line for any writer.
  *
- * \param \wa string of the form writer_name:options
- * \param writer_num contains the number of the writer upon success
+ * \param \wa String of the form writer_name:options.
+ * \param writer_num Contains the number of the writer upon success.
  *
  * This function checks whether \a wa starts with the name of a supported
  * paraslash writer, optionally followed by a colon and any options for that
@@ -98,20 +98,24 @@ void register_writer_node(struct writer_node *wn, struct btr_node *parent)
 }
 
 /**
- * Setup a writer node with the default writer.
+ * Parse config and register a task for a writer node.
  *
- * If arg is \p NULL, the OS-dependent default writer is used with an empty
- * configuration string.  It defaults to alsa for Linux, osx for OS X, oss for
- * *BSD and the file writer if neither of these is supported.
+ * \param arg Command line arguments.
+ * \param parent The new node will be a child of \a parent.
+ * \param wn The writer node.
  *
- * Once the writer configuration has been retrieved, a writer node is created,
- * its buffer tree node is added to the buffer tree as a child of the given
- * parent.
+ * If arg is \p NULL, the OS-dependent default writer is used with no
+ * arguments.  The default writers are alsa for Linux, osx for OS X, oss for
+ * *BSD, and the file writer if the default writer is not supported.
  *
- * Finally, the new writer node's taks structure is initialized and registered
+ * Once the writer configuration has been retrieved from the ->parse_config
+ * callback a writer node is created, its buffer tree node is added to the
+ * buffer tree as a child of the given parent.
+ *
+ * Finally, the new writer node's task structure is initialized and registered
  * to the paraslash scheduler.
  *
- * \return A pointer to the allocated writer node group.
+ * \return Standard.
  */
 int setup_writer_node(const char *arg, struct btr_node *parent,
                struct writer_node *wn)