From b91c9e2f61443577241675cc1eadafd3f2dd8b6e Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Tue, 30 May 2017 21:11:09 +0200 Subject: [PATCH] doxygen: Improve documentation of struct receiver. The documentation still referred to the former gengetopt related ->conf pointer and also had some language and punctuation issues. The new text should fix this, and is more to the point. --- recv.h | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/recv.h b/recv.h index f1e2fc45..6fb70b9a 100644 --- a/recv.h +++ b/recv.h @@ -52,11 +52,9 @@ struct receiver { /** * Open one instance of the receiver. * - * This should allocate the output buffer of \a rn. and may also - * perform any other work necessary for retrieving the stream according - * to the configuration stored in the \a conf member of \a rn which is - * guaranteed to point to valid configuration data (as previously - * obtained from the config parser). + * This should allocate the output buffer of the given receiver node + * and prepare it for retrieving the audio stream according to the + * configuration stored in rn->lpr. * * \sa struct \ref receiver_node. */ @@ -73,31 +71,32 @@ struct receiver { /** * Add file descriptors to fd_sets and compute timeout for select(2). * - * The pre_select function gets called from the driving application - * before entering its select loop. The receiver may use this hook to - * add any file descriptors to the sets of file descriptors given by \a - * s. + * If this is not NULL, the function is called in each iteration of the + * scheduler's select loop. The receiver may define it to add file + * descriptors to the file descriptor sets given by s. Those will be + * monitored in the subsequent call to select(2). The function may also + * lower the timeout value of s to make select(2) return earlier if no + * file descriptors are ready for I/O. * * \sa select(2), \ref time.c, struct \ref sched. */ void (*pre_select)(struct sched *s, void *context); /** - * Evaluate the result from select(). + * Evaluate the result from select(2). * - * This hook gets called after the call to select(). It should check - * all file descriptors which were added to any of the fd sets during - * the previous call to pre_select. According to the result, it may - * then use any non-blocking I/O to establish a connection or to - * receive the audio data. + * This is called after the call to select(2). It should check all file + * descriptors which were added to any of the fd sets in the previous + * call to ->pre_select() and perform (non-blocking) I/O operations on + * those fds which are ready for I/O, for example in order to establish + * a connection or to receive a part of the audio stream. * * \sa select(2), struct \ref receiver. */ int (*post_select)(struct sched *s, void *context); - /** * Answer a buffer tree query. * - * This optional function pointer is used for inter node communications + * This optional function pointer allows for inter node communication * of the buffer tree nodes. See \ref btr_command_handler for details. */ btr_command_handler execute; -- 2.39.2