From 19469a41086a9740bacd8625f1c8d95e820b2477 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nils=20O=2E=20Sel=C3=A5sdal?= <noselasd@fiane.dyndns.org>
Date: Thu, 8 Nov 2012 20:03:38 +0100
Subject: [PATCH] Add docs to GBuf

---
 src/ucore_buffer.c |  4 +--
 src/ucore_buffer.h | 63 ++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 55 insertions(+), 12 deletions(-)

diff --git a/src/ucore_buffer.c b/src/ucore_buffer.c
index a111646..2ed5036 100644
--- a/src/ucore_buffer.c
+++ b/src/ucore_buffer.c
@@ -47,7 +47,7 @@ uc_gbuf_append(GBuf *buf,void *data,size_t len)
 	unsigned char *gbuf;
 	
 	if(buf->len - buf->used < len)
-		if(uc_grow_gbuf(buf, len + len/2))
+		if(uc_gbuf_grow(buf, len + len/2))
 			return -1;
 
 	gbuf = buf->buf;
@@ -58,7 +58,7 @@ uc_gbuf_append(GBuf *buf,void *data,size_t len)
 }
 
 int
-uc_grow_gbuf(GBuf *buf, size_t addlen)
+uc_gbuf_grow(GBuf *buf, size_t addlen)
 {
 	void *tmp;
 	size_t newsz;
diff --git a/src/ucore_buffer.h b/src/ucore_buffer.h
index 9a169b5..0af5a58 100644
--- a/src/ucore_buffer.h
+++ b/src/ucore_buffer.h
@@ -7,29 +7,72 @@
 extern "C" {
 #endif 
 
+
+/** A GBuf is a growing reference counted buffer.
+ * The buffer is dynamically allocated, and can grow
+ * as you append data to it. Reference counting takes care
+ * of automatically freeing the GBuf and its buffer when it
+ * reaches 0
+ */
 typedef struct GBuf GBuf;
 struct GBuf {
+    /** Allocated buffer length.*/
 	size_t len;
+    /** Used space in the buffer */
 	size_t used;
+    /** Reference count */
     size_t ref_cnt;
+    /** The data */
 	void *buf;
 };
 
-GBuf*
-uc_new_gbuf(size_t initsz);
+/** Allocatea new GBuf.
+ *
+ * @param initsz Intial capacity of the GBuf
+ * @return New GBuf, or NULL if allocation fails,
+ * The returned GBuf will have ref_cnt=1
+ */
+GBuf* uc_new_gbuf(size_t initsz);
 
-void
-uc_gbuf_ref(GBuf *buf);
+/** Increment the reference count of the GBuf.
+ *
+ * @param buf Bufffer
+ */
+void uc_gbuf_ref(GBuf *buf);
 
-void
-uc_gbuf_unref(GBuf *buf);
+/** Decrement the reference count of the GBuf, free it if ref_cnt reaches 0
+ *
+ * @param buf Bufffer
+ */
+void uc_gbuf_unref(GBuf *buf);
 
-int 
-uc_gbuf_append(GBuf *buf,void *data,size_t len);
+/** Append data to the GBuf.
+ * Data is coped into the buffer, starting at &buf->data[used]
+ * The GBuf automatically grows if needed.
+ *
+ * @param buf buffer to append to
+ * @param data data to copy to the GBuf
+ * @param len length of @data to copy
+ * @return 0 on success, -1 on failure when allocation fails if he buffer
+ * needs to grow
+ */
+int uc_gbuf_append(GBuf *buf,void *data,size_t len);
 
-int
-uc_grow_gbuf(GBuf *buf, size_t addlen);
+/** Expand the capacity of the GBuf.
+ *
+ * @param buf buffer to grow
+ * @return 0 on success, -1 on failure when allocation fails
+ */
+int uc_gbuf_grow(GBuf *buf, size_t addlen);
 
+/** Remaining unised space of the GBuf.
+ * @param buff buffer
+ * @return length of unused space
+ */
+size_t uc_gbuf_remaining(const GBuf *buf)
+{
+    return buf->len - buf->used;
+}
 
 #ifdef __cplusplus
 }