From: Andre Noll <maan@systemlinux.org>
Date: Fri, 15 Jan 2010 19:22:27 +0000 (+0100)
Subject: [btr] Add more documentation.
X-Git-Tag: v0.4.2~86
X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=d9676861067ac426429a3b76fb5cb237a706d5b3

[btr] Add more documentation.
---

diff --git a/buffer_tree.c b/buffer_tree.c
index 962359fb..9862a4f1 100644
--- 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 0634e63c..0bb31b18 100644
--- 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);