Sanitize swag documentation: group definition in module-xbt; group structure in ...

[simgrid.git] / include / xbt / swag.h

diff --git a/include/xbt/swag.h b/include/xbt/swag.h
index 344eafe..de3090c 100644 (file)
--- a/include/xbt/swag.h
+++ b/include/xbt/swag.h
@@ -19,8 +19,19 @@
 /* Whenever a new object with this struct is created, all fields have
    to be set to NULL */
 
+/** 
+ * \addtogroup XBT_swag
+ * 
+ *  Warning, this module is done to be efficient and performs tons of
+ *  cast and dirty things. So avoid using it unless you really know
+ *  what you are doing. It is basically a fifo but with restrictions so that
+ *  it can be used as a set. Any operation (add, remove, belongs) is O(1) and
+ *  no call to malloc/free is done.
+ *
+ * @{
+ */
+
 /** \name Swag types
-    \ingroup XBT_swag
 
     Specific set. 
 
@@ -67,6 +78,10 @@ typedef struct xbt_swag {
 /**< A typical swag */
 /* @} */
 
+/** \name Functions 
+ */
+/* @{ */
+
 xbt_swag_t xbt_swag_new(size_t offset);
 void xbt_swag_free(xbt_swag_t swag);
 void xbt_swag_init(xbt_swag_t swag, size_t offset);
@@ -86,8 +101,7 @@ static _XBT_INLINE void *xbt_swag_getFirst(xbt_swag_t swag)
 #define xbt_swag_getNext(obj,offset) (((xbt_swag_hookup_t)(((char *) (obj)) + (offset)))->prev)
 #define xbt_swag_getPrev(obj,offset) (((xbt_swag_hookup_t)(((char *) (obj)) + (offset)))->next)
 
-/** 
- * \ingroup XBT_swag
+/**
  * \brief Offset computation
  * \arg var a variable of type <tt>struct</tt> something
  * \arg field a field of <tt>struct</tt> something
@@ -98,23 +112,36 @@ static _XBT_INLINE void *xbt_swag_getFirst(xbt_swag_t swag)
  * Because it is portable...
  */
 #define xbt_swag_offset(var,field) ((char *)&( (var).field ) - (char *)&(var))
+/* @} */
 
 /**
- \name Swag iterator
- \ingroup XBT_swag
+ * \name Swag iterator
  *
  * Iterates over the whole swag. 
- */
-/* @{ */
+ *
+ * @{ */
+
+ /** @brief A simple swag iterator
+  *  @param obj the indice of the loop
+  *  @param swag what to iterate over
+  *  @warning you cannot modify the \a swag while using this loop
+  *  @hideinitializer */
 #define xbt_swag_foreach(obj,swag)                            \
    for((obj)=xbt_swag_getFirst((swag));                       \
        (obj)!=NULL;                                           \
        (obj)=xbt_swag_getNext((obj),(swag)->offset))
-/**<  A simple swag iterator 
- * \param obj the indice of the loop
- * \param swag what to iterate over
 
-    \warning you cannot modify the \a swag while using this loop  */
+/**
+ * @brief A safe swag iterator 
+ * @param obj the indice of the loop
+ * @param obj_next the object that is right after (if any) \a obj in the swag
+ * @param swag what to iterate over
+ * @hideinitializer
+
+    You can safely modify the \a swag while using this loop. 
+    Well, safely... Err. You can remove \a obj without having any 
+    trouble at least.  */
+
 #define xbt_swag_foreach_safe(obj,obj_next,swag)                  \
    for((obj)=xbt_swag_getFirst((swag)),                           \
        ((obj)?(obj_next=xbt_swag_getNext((obj),(swag)->offset)):  \
@@ -123,14 +150,7 @@ static _XBT_INLINE void *xbt_swag_getFirst(xbt_swag_t swag)
        (obj)=obj_next,                                            \
        ((obj)?(obj_next=xbt_swag_getNext((obj),(swag)->offset)):  \
                  (obj_next=NULL))     )
-/**< A safe swag iterator 
- * \param obj the indice of the loop
- * \param obj_next the object that is right after (if any) \a obj in the swag
- * \param swag what to iterate over
-
-    You can safely modify the \a swag while using this loop. 
-    Well, safely... Err. You can remove \a obj without having any 
-    trouble at least.  */
+/* @} */
 /* @} */
 
 #endif    /* _XBT_SWAG_H */