[btr] Add more documentation.

diff --git a/buffer_tree.c b/buffer_tree.c
index 962359fbfa253790880f1380551335eaf9861c6d..9862a4f150b040ddaa1ce2b3b8f842520a52032a 100644 (file)
--- a/buffer_tree.c
+++ b/buffer_tree.c
@@ -136,6 +136,15 @@ size_t btr_pool_available(struct btr_pool *btrp)
        return btrp->rhead - btrp->whead;
 }
 
+/**
+ * Obtain the current write head.
+ *
+ * \param btrp The buffer pool.
+ * \param result The write head is returned here.
+ *
+ * \return The maximal amount of bytes that may be written to the returned
+ * buffer.
+ */
 size_t btr_pool_get_buffer(struct btr_pool *btrp, char **result)
 {
        if (result)
@@ -143,7 +152,16 @@ size_t btr_pool_get_buffer(struct btr_pool *btrp, char **result)
        return btr_pool_available(btrp);
 }
 
-void btr_pool_allocate(struct btr_pool *btrp, size_t size)
+/**
+ * Mark a part of the buffer pool area as allocated.
+ *
+ * \param btrp The buffer pool.
+ * \param size The amount of bytes to be allocated.
+ *
+ * This is usually called after the caller wrote to the buffer obtained by
+ * btr_pool_get_buffer().
+ */
+static void btr_pool_allocate(struct btr_pool *btrp, size_t size)
 {
        char *end;
 
@@ -307,6 +325,12 @@ void btr_add_output(char *buf, size_t size, struct btr_node *btrn)
        add_btrb_to_children(btrb, btrn, 0);
 }
 
+/**
+ * Feed data to child nodes of the buffer tree.
+ *
+ * \param btrp The buffer pool.
+ * 
+ */
 void btr_add_output_pool(struct btr_pool *btrp, size_t size,
                struct btr_node *btrn)
 {
@@ -325,6 +349,17 @@ void btr_add_output_pool(struct btr_pool *btrp, size_t size,
        add_btrb_to_children(btrb, btrn, 0);
 }
 
+/**
+ * Copy data to write head of a buffer pool and feed it to all children nodes.
+ *
+ * \param src The source buffer.
+ * \param n The size of the source buffer in bytes.
+ * \param btrp The destination buffer pool.
+ * \param btrn Add the data as output of this node.
+ *
+ * This is expensive. The caller must make sure the data fits into the buffer
+ * pool area.
+ */
 void btr_copy(const void *src, size_t n, struct btr_pool *btrp,
        struct btr_node *btrn)
 {

diff --git a/buffer_tree.h b/buffer_tree.h
index 0634e63c595ac8adf74dfc235e1e8dd9c9ccd59f..0bb31b188a952cdcf08075af1d4374dc896d1533 100644 (file)
--- a/buffer_tree.h
+++ b/buffer_tree.h
@@ -168,7 +168,6 @@ size_t btr_pool_size(struct btr_pool *btrp);
 struct btr_pool *btr_pool_new(const char *name, size_t area_size);
 void btr_pool_free(struct btr_pool *btrp);
 size_t btr_pool_get_buffer(struct btr_pool *btrp, char **result);
-void btr_pool_allocate(struct btr_pool *btrp, size_t size);
 void btr_add_output_pool(struct btr_pool *btrp, size_t size,
        struct btr_node *btrn);
 size_t btr_pool_unused(struct btr_pool *btrp);