From 9b8de3f5336d148135293e17ddea1e4b4af6004b Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20=C4=8Cun=C3=A1t?= <vladimir.cunat@nic.cz>
Date: Tue, 10 Apr 2018 19:17:10 +0200
Subject: [PATCH] lib/generic/{array,pack}: improve documentation

---
 lib/generic/array.h | 19 +++++++++++--------
 lib/generic/pack.h  | 18 ++++++++++++++----
 2 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/lib/generic/array.h b/lib/generic/array.h
index e3caa13a2..6c4f4b742 100644
--- 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 ddabb0b2a..4b16c9799 100644
--- 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])
-- 
2.47.2