From: Andre Noll Date: Fri, 22 Apr 2011 16:03:28 +0000 (+0200) Subject: doxygen: Add some missing documentation. X-Git-Tag: v0.4.7~6 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=ae8073c5441aeee5d3b63840e84d8c33e2c583ee;hp=da68473d3242606fdc24f65809d97ca6831e6237 doxygen: Add some missing documentation. --- diff --git a/aac_common.c b/aac_common.c index 14662fdd..9e46a77c 100644 --- a/aac_common.c +++ b/aac_common.c @@ -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) { diff --git a/buffer_tree.c b/buffer_tree.c index 0e460dd3..88fb8362 100644 --- a/buffer_tree.c +++ b/buffer_tree.c @@ -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. */ diff --git a/filter.h b/filter.h index 0808059d..94657a73 100644 --- 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. */ diff --git a/filter_common.c b/filter_common.c index 566d97ed..4b1a45de 100644 --- a/filter_common.c +++ b/filter_common.c @@ -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 7217486d..5dc39124 100644 --- 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 05c5ed76..ee8138f9 100644 --- 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. diff --git a/recv_common.c b/recv_common.c index 3fe2a139..f38184b4 100644 --- a/recv_common.c +++ b/recv_common.c @@ -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); diff --git a/ringbuffer.c b/ringbuffer.c index bf990b06..15d767e6 100644 --- a/ringbuffer.c +++ b/ringbuffer.c @@ -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 0044ae4f..8a60294d 100644 --- 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; }; diff --git a/write_common.c b/write_common.c index 5988faf7..faf20749 100644 --- a/write_common.c +++ b/write_common.c @@ -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)