c: minor comment changes

c/include/debug.h

@@ -37,48 +37,61 @@ static inline void _printf debug(_unused u32 level, _unused bool timestamp,
 #undef _unused
 #undef _printf
 
-/* format: only printf
+/**
+ * log - simple log (no function name, no indent, no timestamp)
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
  */
 #define log(level, fmt, args...) \
     debug((level), false, 0, NULL, 0, fmt, ##args)
 
-/* format : indent, no func name, no timestamp
+/**
+ * log_i - log with indent (no function name, no timestamp)
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
+ *
+ * Output example:
  * >>>>val=2
  */
 #define log_i(level, fmt, args...) \
     debug((level), false, (level), NULL, 0, fmt, ##args)
 
-/* format : func name, no indent, no timestamp
- * [foo] val=2
+/**
+ * log_f - log with function name (no indent name, no timestamp)
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
+ *
+ * Output example:
+ * [function] val=2
  */
 #define log_f(level, fmt, args...) \
     debug((level), false, 0, __func__, 0, fmt, ##args)
 
-/* format : func name, no indent, no timestamp
- * >>>> [foo:15] val=2
+/**
+ * log_if - log with function name and line number (no indent name, no timestamp)
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
+ *
+ * Output example:
+ * >>>> [function:15] val=2
  */
 #define log_if(level, fmt, args...) \
     debug((level), false, (level), __func__, __LINE__, fmt, ##args)
 
-/* format : func name, indent, timestamp
- * >>>>foo:15 val=2
+/**
+ * log_it - log with function name, line number, indent, and timestamp
+ * @level:      log level
+ * @fmt:        printf format string
+ * @args:       subsequent arguments to printf
+ *
+ * Output example:
+ * >>>> [function:15] val=2
  */
 #define log_it(level, fmt, args...) \
     debug((level), true, (level), __func__, __LINE__, fmt, ##args)
 
-/* format: file name, no indent, no timestamp
- * foo:15 val=2
- *
- * #define log_f(level, fmt, args...)                            \
- *   debug((level), false, 0, __FILE__, __LINE__, fmt, args)
- */
-
-#else
-#define log(level, fmt, args...)
-#define log_i(...)
-#define log_f(...)
-#define log_if(...)
-#define log_it(...)
-#define log_f(...)
-
-#endif  /* DEBUG_H */
+#endif /* DEBUG_H */

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);