Mercurial > hg > ucx / changeset

--- a/src/cx/collection.h	Sat Jan 04 15:41:02 2025 +0100
+++ b/src/cx/collection.h	Sat Jan 04 16:02:20 2025 +0100
@@ -26,11 +26,11 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 /**
- * \file collection.h
- * \brief Common definitions for various collection implementations.
- * \author Mike Becker
- * \author Olaf Wintermann
- * \copyright 2-Clause BSD License
+ * @file collection.h
+ * @brief Common definitions for various collection implementations.
+ * @author Mike Becker
+ * @author Olaf Wintermann
+ * @copyright 2-Clause BSD License
  */
 
 #ifndef UCX_COLLECTION_H
@@ -96,13 +96,21 @@
 
 /**
  * Use this macro to declare common members for a collection structure.
+ *
+ * @par Example Use
+ * @code
+ * struct MyCustomSet {
+ *     CX_COLLECTION_BASE;
+ *     MySetElements *data;
+ * }
+ * @endcode
  */
 #define CX_COLLECTION_BASE struct cx_collection_s collection
 
 /**
  * Sets a simple destructor function for this collection.
  *
- * @param c the collection
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
  * @param destr the destructor function
  */
 #define cxDefineDestructor(c, destr) \
@@ -111,7 +119,7 @@
 /**
  * Sets a simple destructor function for this collection.
  *
- * @param c the collection
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
  * @param destr the destructor function
  */
 #define cxDefineAdvancedDestructor(c, destr, data) \
@@ -124,8 +132,11 @@
  * Usually only used by collection implementations. There should be no need
  * to invoke this macro manually.
  *
- * @param c the collection
- * @param e the element
+ * When the collection stores pointers, those pointers are directly passed
+ * to the destructor. Otherwise, a pointer to the element is passed.
+ *
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+ * @param e the element (the type is @c void* or @c void** depending on context)
  */
 #define cx_invoke_simple_destructor(c, e) \
     (c)->collection.simple_destructor((c)->collection.store_pointer ? (*((void **) (e))) : (e))
@@ -136,8 +147,11 @@
  * Usually only used by collection implementations. There should be no need
  * to invoke this macro manually.
  *
- * @param c the collection
- * @param e the element
+ * When the collection stores pointers, those pointers are directly passed
+ * to the destructor. Otherwise, a pointer to the element is passed.
+ *
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+ * @param e the element (the type is @c void* or @c void** depending on context)
  */
 #define cx_invoke_advanced_destructor(c, e) \
     (c)->collection.advanced_destructor((c)->collection.destructor_data, \
@@ -150,8 +164,11 @@
  * Usually only used by collection implementations. There should be no need
  * to invoke this macro manually.
  *
- * @param c the collection
- * @param e the element
+ * When the collection stores pointers, those pointers are directly passed
+ * to the destructor. Otherwise, a pointer to the element is passed.
+ *
+ * @param c a pointer to a struct that contains #CX_COLLECTION_BASE
+ * @param e the element (the type is @c void* or @c void** depending on context)
  */
 #define cx_invoke_destructor(c, e) \
     if ((c)->collection.simple_destructor) cx_invoke_simple_destructor(c,e); \