From 53df2f10610a1118332e6fe650a10dc32bc5a37d Mon Sep 17 00:00:00 2001 From: mquinson Date: Mon, 30 May 2005 14:11:09 +0000 Subject: [PATCH 1/1] Sanitize swag documentation: group definition in module-xbt; group structure in .h; element documentation still in .c git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@1298 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- doc/module-xbt.doc | 7 ++++-- include/xbt/swag.h | 58 +++++++++++++++++++++++++++++++--------------- src/xbt/swag.c | 15 ------------ 3 files changed, 44 insertions(+), 36 deletions(-) diff --git a/doc/module-xbt.doc b/doc/module-xbt.doc index 476dd76e7e..07a6689644 100644 --- a/doc/module-xbt.doc +++ b/doc/module-xbt.doc @@ -77,8 +77,11 @@ /** \addtogroup XBT_fifo \ingroup XBT_API */ -/** \addtogroup XBT_swag - \ingroup XBT_API */ + + /** @defgroup XBT_swag A O(1) set datatype + * @brief a O(1) set based on linked lists + */ + /** \addtogroup XBT_heap \ingroup XBT_API */ diff --git a/include/xbt/swag.h b/include/xbt/swag.h index 344eafe99a..de3090cb3f 100644 --- 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 struct something * \arg field a field of struct 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 */ diff --git a/src/xbt/swag.c b/src/xbt/swag.c index dd837835c8..ec8e4c7f93 100644 --- a/src/xbt/swag.c +++ b/src/xbt/swag.c @@ -15,25 +15,11 @@ #include "xbt/error.h" #include "xbt/swag.h" -/** \defgroup XBT_swag A O(1) set datatype - * \brief a O(1) set based on linked lists - * - * 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. - */ - XBT_LOG_NEW_DEFAULT_SUBCATEGORY(swag,xbt,"Swag : O(1) set library"); #define PREV(obj,offset) xbt_swag_getPrev(obj,offset) #define NEXT(obj,offset) xbt_swag_getNext(obj,offset) -/** \name Functions - * \ingroup XBT_swag - */ -/* @{ */ /** Creates a new swag. * \param offset where the hookup is located in the structure @@ -239,4 +225,3 @@ int xbt_swag_belongs(void *obj, xbt_swag_t swag) return ((NEXT(obj, swag->offset)) || (PREV(obj, swag->offset)) || (swag->head == obj)); } -/* @} */ -- 2.20.1