[btr] Add more documentation.

diff --git a/buffer_tree.c b/buffer_tree.c
index aff03444cc8cc3d0181812fc677c03bfa132e3b0..201fb0b0e21ac4556b12968b3e22cde23fd5c302 100644 (file)
--- a/buffer_tree.c
+++ b/buffer_tree.c
@@ -57,8 +57,7 @@ struct btr_node {
  * Create a new buffer pool.
  *
  * \param name The name of the new buffer pool.
- *
- * \param area The size in bytes of the pool area.
+ * \param area_size The size in bytes of the pool area.
  *
  * \return An opaque pointer to the newly created buffer pool. It must be
  * passed to btr_pool_free() after it is no longer used to deallocate all
@@ -79,7 +78,7 @@ struct btr_pool *btr_pool_new(const char *name, size_t area_size)
 }
 
 /**
- * Dellocate resources used by a buffer pool.
+ * Deallocate resources used by a buffer pool.
  *
  * \param btrp A pointer obtained via btr_pool_new().
  */
@@ -222,9 +221,9 @@ static void btr_pool_deallocate(struct btr_pool *btrp, size_t size)
  *
  * \param bnd Specifies how to create the new node.
  *
- * This function always succeeds (or calls exit()). The returned pointer
- * must be freed using btr_free_node() after it has been removed from
- * the buffer tree via btr_remove_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().
  */
 struct btr_node *btr_new_node(struct btr_node_description *bnd)
 {
@@ -424,6 +423,15 @@ static void btr_pushdown_br(struct btr_buffer_reference *br, struct btr_node *bt
        btr_drop_buffer_reference(br);
 }
 
+/**
+ * Feed all buffer references of the input queue through the output channel.
+ *
+ * \param btrn The node whose buffer references should be pushed down.
+ *
+ * This function is useful for filters that do not change the contents of the
+ * buffers at all, like the wav filter or the amp filter if no amplification
+ * was specified. This function is rather cheap.
+ */
 void btr_pushdown(struct btr_node *btrn)
 {
        struct btr_buffer_reference *br, *tmp;
@@ -596,6 +604,11 @@ static void flush_input_queue(struct btr_node *btrn)
                btr_drop_buffer_reference(br);
 }
 
+/**
+ * Free all resources allocated by btr_new_node().
+ *
+ * Like free(3), it is OK to call this with a \p NULL pointer argument.
+ */
 void btr_free_node(struct btr_node *btrn)
 {
        if (!btrn)
@@ -604,6 +617,17 @@ void btr_free_node(struct btr_node *btrn)
        free(btrn);
 }
 
+/**
+ * Remove a node from a buffer tree.
+ *
+ * \param btrn The node to remove.
+ *
+ * This makes all child nodes of \a btrn orphans and removes \a btrn from the
+ * list of children of its parent. Moreover, the input queue of \a btrn is
+ * flushed if it is not empty.
+ *
+ * \sa \ref btr_splice_out_node.
+ */
 void btr_remove_node(struct btr_node *btrn)
 {
        struct btr_node *ch;
@@ -646,6 +670,17 @@ size_t btr_get_input_queue_size(struct btr_node *btrn)
        return size;
 }
 
+/**
+ * Remove a node from the buffer tree, reconnecting parent and children.
+ *
+ * \param btrn The node to splice out.
+ *
+ * This function is used by buffer tree nodes that do not exist during the
+ * whole lifetime of the buffer tree. Unlike btr_remove_node(), calling
+ * btr_splice_out_node() does not split the tree into disconnected components
+ * but reconnects the buffer tree by making all child nodes of \a btrn children
+ * of the parent of \a btrn.
+ */
 void btr_splice_out_node(struct btr_node *btrn)
 {
        struct btr_node *ch, *tmp;
@@ -692,7 +727,18 @@ int btr_exec(struct btr_node *btrn, const char *command, char **value_result)
 }
 
 /**
- * Execute a inter-node command.
+ * Execute a inter-node command on a parent node.
+ *
+ * \param btrn The node to start looking.
+ * \param command The command to execute.
+ * \param value_result Additional arguments and result value.
+ *
+ * This function traverses the buffer tree upwards and looks for parent nodes
+ * of \a btrn that understands \a command. On the first such node the command
+ * is executed, and the result is stored in \a value_result.
+ *
+ * \return \p -ENOTSUP if no parent node of \a btrn understands \a command.
+ * Otherwise the return value of the command handler is returned.
  */
 int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result)
 {
@@ -718,6 +764,14 @@ int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result)
        return -ERRNO_TO_PARA_ERROR(ENOTSUP);
 }
 
+/**
+ * Obtain the context of a buffer node tree.
+ *
+ * The returned pointer equals the context pointer used at creation time of the
+ * node.
+ *
+ * \sa btr_new_node(), struct \ref btr_node_description.
+ */
 void *btr_context(struct btr_node *btrn)
 {
        return btrn->context;
@@ -869,6 +923,20 @@ static int merge_input(struct btr_node *btrn)
        return 2;
 }
 
+/**
+ * Combine input queue buffers.
+ *
+ * \param btrn The buffer tree node whose input should be merged.
+ * \param dest_size Stop merging if a buffer of at least this size exists.
+ *
+ * Used to combine as many buffers as needed into a single buffer whose size is
+ * at least \a dest_size. This function is rather cheap in case the parent node
+ * uses buffer pools and rather expensive otherwise.
+ *
+ * Note that if less than \a dest_size bytes are available in total, this
+ * function does nothing and subsequent calls to btr_next_buffer() will still
+ * return a buffer size less than \a dest_size.
+ */
 void btr_merge(struct btr_node *btrn, size_t dest_size)
 {
        if (need_buffer_pool_merge(btrn))

diff --git a/buffer_tree.h b/buffer_tree.h
index 157c17c25445456c844258d806bf5bd120f83a9e..305fb7d1a43cddc8fe5b6034e271587f9da9b6a7 100644 (file)
--- a/buffer_tree.h
+++ b/buffer_tree.h
@@ -187,7 +187,6 @@ void btr_splice_out_node(struct btr_node *btrn);
 void btr_pushdown(struct btr_node *btrn);
 void *btr_context(struct btr_node *btrn);
 void btr_merge(struct btr_node *btrn, size_t dest_size);
-bool btr_eof(struct btr_node *btrn);
 void btr_log_tree(struct btr_node *btrn, int loglevel);
 int btr_pushdown_one(struct btr_node *btrn);
 bool btr_inplace_ok(struct btr_node *btrn);