Remove from documentation struct names not used.

[bertos.git] / bertos / struct / pool.h

diff --git a/bertos/struct/pool.h b/bertos/struct/pool.h
index b2e14148ab2cea61f95d59c26afeced5b47b8677..a44b14f3518b04d573290b573caaddb94a046209 100644 (file)
--- a/bertos/struct/pool.h
+++ b/bertos/struct/pool.h
@@ -31,7 +31,6 @@
  *
  * \brief Pool macros.
  *
- * \version $Id: pool.h 1294 2008-05-20 13:43:57Z asterix $
  * \author Giovanni Bajo <rasky@develer.com>
  */
 
@@ -49,7 +48,7 @@
        storage name; \
        INLINE void name##_init(void (*init_func)(type*)) \
        { \
-               int i; \
+               size_t i; \
                LIST_INIT(&name); \
                for (i=0;i<countof(name##_items);++i) \
                { \
@@ -60,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)
 
@@ -67,8 +76,38 @@
        DECLARE_POOL_WITH_STORAGE(name, type, num, static List)
 
 #define pool_init(name, init_func)     (*(name##_init))(init_func)
-#define pool_alloc(name)               REMHEAD(name)
+
+/**
+ * \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 */