lib/generic/{array,pack}: improve documentation

diff --git a/lib/generic/array.h b/lib/generic/array.h
index e3caa13a23d03486545b34086cab1c9c508f78d9..6c4f4b7428faa68233d9fd93b9b8f830a5532b2a 100644 (file)
--- a/lib/generic/array.h
+++ b/lib/generic/array.h
@@ -104,25 +104,28 @@ static inline void array_std_free(void *baton, void *p)
 /** Zero-initialize the array. */
 #define array_init(array) ((array).at = NULL, (array).len = (array).cap = 0)
 
-/** Free and zero-initialize the array. */
+/** Free and zero-initialize the array (plain malloc/free). */
 #define array_clear(array) \
        array_clear_mm(array, array_std_free, NULL)
-/** @internal Clear array with a callback. */
+
+/** Make the array empty and free pointed-to memory.
+ * Mempool usage: pass mm_free and a knot_mm_t* . */
 #define array_clear_mm(array, free, baton) \
        (free)((baton), (array).at), array_init(array)
 
-/**
- * Reserve capacity up to 'n' bytes.
- * @return 0 if success, <0 on failure
- */
+/** Reserve capacity for at least n elements.
+ * @return 0 if success, <0 on failure */
 #define array_reserve(array, n) \
        array_reserve_mm(array, n, array_std_reserve, NULL)
-/** @internal Reserve capacity using callback. */
+
+/** Reserve capacity for at least n elements.
+ * Mempool usage: pass kr_memreserve and a knot_mm_t* .
+ * @return 0 if success, <0 on failure */
 #define array_reserve_mm(array, n, reserve, baton) \
        (reserve)((baton), (char **) &(array).at, sizeof((array).at[0]), (n), &(array).cap)
 
 /**
- * Push value at the end of the array, resize it if necessary.
+ * Push value at the end of the array, resize it if necessary (malloc/free).
  * @note May fail if the capacity is not reserved.
  * @return element index on success, <0 on failure
  */

diff --git a/lib/generic/pack.h b/lib/generic/pack.h
index ddabb0b2a61a61f2f6440fbce26188c456cb95fa..4b16c9799cc5ef7df30cd90ca73845be977335b2 100644 (file)
--- a/lib/generic/pack.h
+++ b/lib/generic/pack.h
@@ -75,21 +75,31 @@ typedef array_t(uint8_t) pack_t;
 /** Zero-initialize the pack. */
 #define pack_init(pack) \
        array_init(pack)
-/** Free and the pack. */
+
+/** Make the pack empty and free pointed-to memory (plain malloc/free). */
 #define pack_clear(pack) \
        array_clear(pack)
-/** @internal Clear pack with a callback. */
+
+/** Make the pack empty and free pointed-to memory.
+ * Mempool usage: pass mm_free and a knot_mm_t* . */
 #define pack_clear_mm(pack, free, baton) \
        array_clear_mm((pack), (free), (baton))
-/** Incrementally reserve objects in the pack. */
+
+/** Reserve space for *additional* objects in the pack (plain malloc/free).
+ * @return 0 if success, <0 on failure */
 #define pack_reserve(pack, objs_count, objs_len) \
        pack_reserve_mm((pack), (objs_count), (objs_len), array_std_reserve, NULL)
-/** @internal Reservation with a callback. */
+
+/** Reserve space for *additional* objects in the pack.
+ * Mempool usage: pass kr_memreserve and a knot_mm_t* .
+ * @return 0 if success, <0 on failure */
 #define pack_reserve_mm(pack, objs_count, objs_len, reserve, baton) \
        array_reserve_mm((pack), (pack).len + (sizeof(pack_objlen_t)*(objs_count) + (objs_len)), (reserve), (baton))
+
 /** Return pointer to first packed object. */
 #define pack_head(pack) \
        ((pack).len > 0 ? &((pack).at[0]) : NULL)
+
 /** Return pack end pointer. */
 #define pack_tail(pack) \
        &((pack).at[(pack).len])