X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=bertos%2Fstruct%2Fpool.h;h=a44b14f3518b04d573290b573caaddb94a046209;hb=4bef9e1478a89338bece87b04c3872e76b64068e;hp=f53d4061c828bb3679ddf3381cd201922811bf4a;hpb=1545cffc84576287b43e3f873eed0df3c8f8c20a;p=bertos.git

diff --git a/bertos/struct/pool.h b/bertos/struct/pool.h
index f53d4061..a44b14f3 100644
--- a/bertos/struct/pool.h
+++ b/bertos/struct/pool.h
@@ -59,6 +59,16 @@
 	INLINE void name##_init(void (*init_func)(type*)) \
 	/**/
 
+/**
+ * \brief Helper macro to declare a Pool data type.
+ *
+ * Data type inserted into the pool must be a \code Node * \endcode
+ * type.
+ *
+ * \param name Variable name of the pool.
+ * \param type Data type held by the pool.
+ * \param num Number of elements in pool.
+ */
 #define DECLARE_POOL(name, type, num) \
 	DECLARE_POOL_WITH_STORAGE(name, type, num, List)
 
@@ -66,8 +76,38 @@
 	DECLARE_POOL_WITH_STORAGE(name, type, num, static List)
 
 #define pool_init(name, init_func)     (*(name##_init))(init_func)
+
+/**
+ * \brief Allocate an element from the pool.
+ *
+ * The returned element is of type \code Node * \endcode, it's safe to
+ * cast it to the type contained in the pool.
+ *
+ * \note If the element was recycled with pool_free(), it will not be reset,
+ * so don't assume that the element has specific values.
+ *
+ * \param name Pointer to pool to alloc from.
+ * \return Element of the type present in the pool.
+ */
 #define pool_alloc(name)               list_remHead(name)
+
+/**
+ * \brief Recycle an element into the pool
+ *
+ * \note Element fields are not reset to its original values, keep that in
+ * mind when you alloc nodes.
+ *
+ * \param name Pointer to pool where the node should be recycled.
+ * \param elem Element to be recycled.
+ */
 #define pool_free(name, elem)          ADDHEAD(name, (Node*)elem)
-#define pool_empty(name)               ISLISTEMPTY(name)
+
+/**
+ * \brief Test if the pool is empty
+ *
+ * \param name Pointer to pool.
+ * \return True if the pool is empty, false otherwise.
+ */
+#define pool_empty(name)               LIST_EMPTY(name)
 
 #endif /* STRUCT_POOL_H */