c: minor comment changes

c/include/pool.h

@@ -28,10 +28,10 @@ typedef struct {
 
 typedef struct {
     char name[POOL_NAME_LENGTH];                  /* pool name */
+    size_t eltsize;                               /* object size */
     u32 available;                                /* current available elements */
     u32 allocated;                                /* total objects allocated */
     u32 growsize;                                 /* number of objects per block allocated */
-    size_t eltsize;                               /* object size */
     u32 nblocks;                                  /* number of blocks allocated */
     struct list_head list_available;              /* available nodes */
     struct list_head list_blocks;                 /* allocated blocks */
@@ -48,29 +48,42 @@ void pool_stats(pool_t *pool);
  * @name:    the name to give to the pool.
  * @grow:    the number of elements to add when no more available.
  * @size:    the size of an element in pool.
+ *
+ * The name will be truncated to 16 characters (including the final '\0').
+ *
+ * Return:   The address of the created pool, or NULL if error.
  */
 pool_t *pool_create(const char *name, u32 grow, size_t size);
 
 /**
- * pool_get - get an element from a pool
- * @pool:    the pool address.
+ * pool_get() - Get an element from a pool.
+ * @pool:    The pool address.
+ *
+ * Get an object from the pool.
+ *
+ * Return:   The address of the object, or NULL if error.
  */
 void *pool_get(pool_t *pool);
 
 /**
- * pool_add - add (release) an element to a pool
- * @pool:    the pool address.
- * @elt:     the address of the object to add to the pool.
+ * pool_add() - Add (free) an element to a pool.
+ * @pool:    The pool address.
+ * @elt:     The address of the object to add to the pool.
+ *
+ * The object will be available for further pool_get().
+ *
+ * Return:   The current number of available elements in pool (including
+ *           @elt).
  */
 u32 pool_add(pool_t *pool, void *elt);
 
 /**
- * pool_destroy - destroy a pool.
- * @pool:    the pool address.
+ * pool_destroy() - destroy a pool.
+ * @pool:    The pool address.
  *
  * Attention: All memory is freed, but no check is done whether all pool
- * elements has been released. Referencing any pool object after this call
- * is strongly discouraged.
+ * elements have been released. Referencing any pool object after this call
+ * will likely imply some memory corruption.
  */
 void pool_destroy(pool_t *pool);