Updated doc

lib/spdylay_buffer.h

@@ -30,7 +30,6 @@
 #endif /* HAVE_CONFIG_H */
 
 #include <spdylay/spdylay.h>
-#include "spdylay_queue.h"
 
 typedef struct spdylay_buffer_chunk {
   uint8_t *data;
@@ -67,9 +66,17 @@ size_t spdylay_buffer_avail(spdylay_buffer *buffer);
 /* Advances buffer pointer by amount. This reduces available buffer
    length. */
 void spdylay_buffer_advance(spdylay_buffer *buffer, size_t amount);
-/* Allocate new chunk buffer. This will increase total length of
-   buffer (returned by spdylay_buffer_length) by capacity-last_offset.
-   It means untouched buffer is assumued to be written. */
+/*
+ * Allocate new chunk buffer. This will increase total length of
+ * buffer (returned by spdylay_buffer_length) by capacity-last_offset.
+ * It means untouched buffer is assumued to be written.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative eror codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
+ */
 int spdylay_buffer_alloc(spdylay_buffer *buffer);
 
 /* Returns total length of buffer */

lib/spdylay_helper.h

@@ -61,10 +61,15 @@ uint32_t spdylay_get_uint32(const uint8_t *data);
  * allocates new buffer having at least |min_length| bytes and assigns
  * its pointer to |*buf_ptr| and allocated number of bytes to
  * |*buflen_ptr|. The memory pointed by |*buf_ptr| previously is
- * freed. No memory copy is done between old and new buffer.  This
- * function returns 0 if it succeeds, or negative error code.
+ * freed. No memory copy is done between old and new buffer.
  * |*buf_ptr| and |*buflen_ptr| are only updated iff this function
  * succeeds.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
  */
 int spdylay_reserve_buffer(uint8_t **buf_ptr, size_t *buflen_ptr,
                            size_t min_length);

lib/spdylay_pq.h

@@ -35,22 +35,60 @@
 /* Implementation of priority queue */
 
 typedef struct {
+  /* The pointer to the pointer to the item stored */
   void **q;
+  /* The number of items sotred */
   size_t length;
+  /* The maximum number of items this pq can store. This is
+     automatically extended when length is reached to this value. */
   size_t capacity;
+  /* The compare function between items */
   spdylay_compar compar;
 } spdylay_pq;
 
+/*
+ * Initializes priority queue |pq| with compare function |cmp|.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
+ */
 int spdylay_pq_init(spdylay_pq *pq, spdylay_compar cmp);
 
+/*
+ * Deallocates any resources allocated for |pq|.  The stored items are
+ * not freed by this function.
+ */
 void spdylay_pq_free(spdylay_pq *pq);
 
+/*
+ * Adds |item| to the priority queue |pq|.
+ *
+ * This function returns 0 if it succeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
+ */
 int spdylay_pq_push(spdylay_pq *pq, void *item);
 
+/*
+ * Returns item at the top of the queue |pq|. If the queue is empty,
+ * this function returns NULL.
+ */
 void* spdylay_pq_top(spdylay_pq *pq);
 
+/*
+ * Pops item at the top of the queue |pq|. The popped item is not
+ * freed by this function.
+ */
 void spdylay_pq_pop(spdylay_pq *pq);
 
+/*
+ * Returns nonzero if the queue |pq| is empty.
+ */
 int spdylay_pq_empty(spdylay_pq *pq);
 
 #endif /* SPDYLAY_PQ_H */

lib/spdylay_zlib.c

@@ -72,14 +72,14 @@ int spdylay_zlib_inflate_hd_init(spdylay_zlib *inflater)
   return 0;
 }
 
-void spdylay_zlib_deflate_free(spdylay_zlib *zlib)
+void spdylay_zlib_deflate_free(spdylay_zlib *deflater)
 {
-  deflateEnd(&zlib->zst);
+  deflateEnd(&deflater->zst);
 }
 
-void spdylay_zlib_inflate_free(spdylay_zlib *zlib)
+void spdylay_zlib_inflate_free(spdylay_zlib *inflater)
 {
-  inflateEnd(&zlib->zst);
+  inflateEnd(&inflater->zst);
 }
 
 ssize_t spdylay_zlib_deflate_hd(spdylay_zlib *deflater,

lib/spdylay_zlib.h

@@ -32,24 +32,81 @@
 
 #include "spdylay_buffer.h"
 
+/* This structure is used for both deflater and inflater. */
 typedef struct {
   z_stream zst;
 } spdylay_zlib;
 
+/*
+ * Initializes |deflater| for deflating name/values pairs in the
+ * frame.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_ZLIB
+ *     The z_stream initialization failed.
+ */
 int spdylay_zlib_deflate_hd_init(spdylay_zlib *deflater);
 
+/*
+ * Initializes |inflater| for inflating name/values pairs in the
+ * frame.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * SPDYLAY_ERR_ZLIB
+ *     The z_stream initialization failed.
+ */
 int spdylay_zlib_inflate_hd_init(spdylay_zlib *inflater);
 
-void spdylay_zlib_deflate_free(spdylay_zlib *zlib);
+/*
+ * Deallocates any resources allocated for |deflater|.
+ */
+void spdylay_zlib_deflate_free(spdylay_zlib *deflater);
 
-void spdylay_zlib_inflate_free(spdylay_zlib *zlib);
+/*
+ * Deallocates any resources allocated for |inflater|.
+ */
+void spdylay_zlib_inflate_free(spdylay_zlib *inflater);
 
+/*
+ * Returns the maximum length when |len| bytes of data are deflated by
+ * |deflater|.
+ */
 size_t spdylay_zlib_deflate_hd_bound(spdylay_zlib *deflater, size_t len);
 
+/*
+ * Deflates data stored in |in| with length |inlen|. The output is
+ * written to |out| with length |outlen|. This is not a strict
+ * requirement but |outlen| should have at least
+ * spdylay_zlib_deflate_hd_bound(|inlen|) bytes for successful
+ * operation.
+ *
+ * This function returns the number of bytes outputted if it succeeds,
+ * or one of the following negative error codes:
+ *
+ * SPDYLAY_ERR_ZLIB
+ *     The deflate operation failed.
+ */
 ssize_t spdylay_zlib_deflate_hd(spdylay_zlib *deflater,
                                 uint8_t *out, size_t outlen,
                                 const uint8_t *in, size_t inlen);
 
+/*
+ * Inflates data stored in |in| with length |inlen|.  The output is
+ * added to |buf|.
+ *
+ * This function returns the number of bytes outputted if it succeeds,
+ * or one of the following negative error codes:
+ *
+ * SPDYLAY_ERR_ZLIB
+ *     The inflate operation failed.
+ *
+ * SPDYLAY_ERR_NOMEM
+ *     Out of memory.
+ */
 ssize_t spdylay_zlib_inflate_hd(spdylay_zlib *inflater,
                                 spdylay_buffer* buf,
                                 const uint8_t *in, size_t inlen);