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

[btr] Add more documentation.
---

diff --git a/buffer_tree.c b/buffer_tree.c
index 6dc3c41b..962359fb 100644
--- a/buffer_tree.c
+++ b/buffer_tree.c
@@ -8,6 +8,7 @@
 #include "error.h"
 #include "sched.h"
 
+/* whead = NULL means area full */
 struct btr_pool {
 	char *name;
 	char *area_start;
@@ -56,6 +57,17 @@ struct btr_node {
 	void *context;
 };
 
+/**
+ * Create a new buffer pool.
+ *
+ * \param name The name of the new buffer pool.
+ *
+ * \param area 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
+ * resources.
+ */
 struct btr_pool *btr_pool_new(const char *name, size_t area_size)
 {
 	struct btr_pool *btrp;
@@ -70,8 +82,11 @@ struct btr_pool *btr_pool_new(const char *name, size_t area_size)
 	return btrp;
 }
 
-/* whead = NULL means area full */
-
+/**
+ * Dellocate resources used by a buffer pool.
+ *
+ * \param btrp A pointer obtained via btr_pool_new().
+ */
 void btr_pool_free(struct btr_pool *btrp)
 {
 	if (!btrp)
@@ -81,6 +96,14 @@ void btr_pool_free(struct btr_pool *btrp)
 	free(btrp);
 }
 
+/**
+ * Return the size of the buffer pool area.
+ *
+ * \param btrp The buffer pool.
+ *
+ * \return The same value which was passed during creation time to
+ * btr_pool_new().
+ */
 size_t btr_pool_size(struct btr_pool *btrp)
 {
 	return btrp->area_end - btrp->area_start;