[btr] Add more documentation.

diff --git a/buffer_tree.c b/buffer_tree.c
index 6dc3c41b2b9deb6787c1e6414e0f43ce394355af..962359fbfa253790880f1380551335eaf9861c6d 100644 (file)
--- 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;