From 9f091df92f0ee7966a3a75ff8461a134c93214a9 Mon Sep 17 00:00:00 2001 From: mquinson Date: Fri, 11 Feb 2005 14:52:20 +0000 Subject: [PATCH 1/1] doxygenification of XBT git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@981 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- ChangeLog | 3 + doc/Doxyfile.API.in | 1 + doc/modules.doc | 41 --------- include/xbt/dict.h | 190 ++++++++++++++++++++++++++---------------- include/xbt/error.h | 137 ++++++++++++++++++------------ src/xbt/dict.c | 63 ++++++-------- src/xbt/dict_cursor.c | 62 ++++---------- src/xbt/error.c | 8 +- src/xbt/log.c | 3 +- 9 files changed, 252 insertions(+), 256 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6593e2777a..0247f9efa3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,6 @@ +2005-02-11 Martin + - Documentation overhault. + 2005-02-08 Martin - Doxygenification of all GRAS. gtk-doc-tools is dead in SimGrid now. - Automatically extract all existing logging categories, and add the list diff --git a/doc/Doxyfile.API.in b/doc/Doxyfile.API.in index dfd7d95780..750ccb497c 100644 --- a/doc/Doxyfile.API.in +++ b/doc/Doxyfile.API.in @@ -408,6 +408,7 @@ INPUT = @top_srcdir@/include/ \ @top_srcdir@/src/xbt/ \ @srcdir@/modules.doc \ @srcdir@/module-gras.doc \ + @srcdir@/module-xbt.doc \ ./api_index.doc \ ./logcategories.doc diff --git a/doc/modules.doc b/doc/modules.doc index 2b8d74d98e..40ea7f265f 100644 --- a/doc/modules.doc +++ b/doc/modules.doc @@ -6,47 +6,6 @@ \brief The core toolbox of SimGrid, containing usefull datatypes, portability support and so on. */ -/** \defgroup XBT_ground Grounding features of the XBT (logging and error reporting) - \ingroup XBT_API */ - /** \addtogroup XBT_log - \ingroup XBT_ground */ - /** \defgroup XBT_log_cats Existing log categories - \ingroup XBT_log - \brief (automatically extracted) - - This is the list of all existing log categories in SimGrid. - This list was automatically extracted from the source code by - the src/xbt_log_extract_hierarchy utility. - - You can thus be certain that it is uptodate, but it may somehow - lack a final manual touch. - Anyway, nothing's perfect ;) - */ - /** \addtogroup XBT_error - \ingroup XBT_ground */ - -/** \defgroup XBT_structs Datatypes defined in the XBT - \ingroup XBT_API */ -/** \addtogroup XBT_dict - \ingroup XBT_structs */ -/** \addtogroup XBT_dynar - \ingroup XBT_structs */ -/** \addtogroup XBT_fifo - \ingroup XBT_structs */ -/** \addtogroup XBT_set - \ingroup XBT_structs */ -/** \addtogroup XBT_swag - \ingroup XBT_structs */ -/** \addtogroup XBT_heap - \ingroup XBT_structs */ - -/** \defgroup XBT_port Portability support defined in the XBT - (you shouldn't use it directly) - \ingroup XBT_API */ -/** \addtogroup XBT_context - \ingroup XBT_port */ -/** \addtogroup XBT_sysdep - \ingroup XBT_port */ /** \defgroup SURF_API SURF \ingroup SimGrid_API diff --git a/include/xbt/dict.h b/include/xbt/dict.h index c337b2dd8c..8153b3ede9 100644 --- a/include/xbt/dict.h +++ b/include/xbt/dict.h @@ -16,64 +16,135 @@ BEGIN_DECL() -/*####[ Type definition ]####################################################*/ -/** \brief Dictionnary data type - \ingroup XBT_dict +/** @addtogroup XBT_dict + * + * This section describes the API to a dictionnary structure that + * associates as string to a void* key. Even if it provides the same + * functionnality than an hash table, the implementation differs and the + * internal data-structure rather looks like a tree. + * + * Here is a little example of use: + * \verbatim xbt_dict_t mydict = xbt_dict_new(); + char buff[512]; + + sprintf(buff,"some very precious data"); + xbt_dict_set(mydict,"my data", strdump(buff), free); + + sprintf(buff,"another good stuff"); + xbt_dict_set(mydict,"my data", strdup(buff), free); // previous data gets erased (and freed) by second add \endverbatim + + * + * \warning This section also gets bitten by the doxygen bug reordering the name sections. + * Make sure to read in this order: + * -# Constructor/destructor + * -# Dictionnaries basic usage + * -# Non-null terminated keys + * -# Traversing dictionnaries with cursors + * + * @{ */ -typedef struct xbt_dict_ *xbt_dict_t; -/*####[ Simple dict functions ]#############################################*/ +/** @name 1. Constructor/destructor + * @{ + */ + + /** \brief Dictionnary data type (opaque structure) */ + typedef struct xbt_dict_ *xbt_dict_t; + xbt_dict_t xbt_dict_new(void); + void xbt_dict_free(xbt_dict_t *dict); + +/** @} */ +/** @name 2. Dictionnaries basic usage + * + * Careful, those functions assume that the key is null-terminated. + * + * @{ */ + + void xbt_dict_set(xbt_dict_t head, const char *key, void *data, void_f_pvoid_t *free_ctn); + xbt_error_t xbt_dict_get(xbt_dict_t head,const char *key, /* OUT */void **data); + xbt_error_t xbt_dict_remove(xbt_dict_t head,const char *key); + void xbt_dict_dump(xbt_dict_t head,void (*output)(void*)); + +/** @} */ +/** @name 3. Non-null terminated keys + * + * Those functions work even with non-null terminated keys. + * + * @{ + */ + void xbt_dict_set_ext(xbt_dict_t head, + const char *key, int key_len, + void *data, + void_f_pvoid_t *free_ctn); + xbt_error_t xbt_dict_get_ext(xbt_dict_t head,const char *key, int key_len, + /* OUT */void **data); + xbt_error_t xbt_dict_remove_ext(xbt_dict_t head, + const char *key, int key_len); -xbt_dict_t xbt_dict_new(void); -void xbt_dict_free(xbt_dict_t *dict); +/** @} */ +/** @name 4. Cursors on dictionnaries + * + * Don't get impressed, there is a lot of functions here, but traversing a + * dictionnary is imediate with the xbt_dict_foreach macro. + * You only need the other functions in rare cases (they are not used directly in SG itself). + * + * Here is an example (assuming that the dictionnary contains strings, ie + * that the data argument of xbt_dict_set was always a null-terminated char*): +\verbatim xbt_dict_cursor_t cursor=NULL; + char *key,*data; -void xbt_dict_set (xbt_dict_t head, - const char *key, - void *data, - void_f_pvoid_t *free_ctn); -void xbt_dict_set_ext(xbt_dict_t head, - const char *key, - int key_len, - void *data, - void_f_pvoid_t *free_ctn); + xbt_dict_foreach(head,cursor,key,data) { + printf(" - Seen: %s->%s\n",key,data); + }\endverbatim -/*----[ xbt_dict_get ]------------------------------------------------------*/ -/* Search the given #key#. data=NULL when not found. */ -/* Returns true if anything went ok, and false on internal error. */ -/*---------------------------------------------------------------------------*/ -xbt_error_t xbt_dict_get(xbt_dict_t head,const char *key, - /* OUT */void **data); -xbt_error_t xbt_dict_get_ext(xbt_dict_t head,const char *key, - int key_len, - /* OUT */void **data); -/*----[ xbt_dict_remove ]---------------------------------------------------*/ -/* Remove the entry associated with the given #key#. */ -/* Returns if ok. Removing a non-existant key is ok. */ -/*---------------------------------------------------------------------------*/ -xbt_error_t xbt_dict_remove(xbt_dict_t head,const char *key); + * + * \warning Do not add or remove entries to the cache while traversing !! + * + * @{ */ -xbt_error_t xbt_dict_remove_ext(xbt_dict_t head, - const char *key, int key_len); + /** \brief Cursor on dictionnaries (opaque type) */ + typedef struct xbt_dict_cursor_ *xbt_dict_cursor_t; + xbt_dict_cursor_t xbt_dict_cursor_new(const xbt_dict_t head); + void xbt_dict_cursor_free(xbt_dict_cursor_t *cursor); + + void xbt_dict_cursor_rewind(xbt_dict_cursor_t cursor); -/*----[ xbt_dict_dump ]-----------------------------------------------------*/ -/* Outputs the content of the structure. (for debuging purpose) */ -/* #output# is a function to output the data.If NULL, data won't be displayed*/ -/*---------------------------------------------------------------------------*/ -void xbt_dict_dump(xbt_dict_t head, - void (*output)(void*)); -/*----[ xbt_dict_print ]----------------------------------------------------*/ -/* To dump multicache, this function dump a cache */ -/*---------------------------------------------------------------------------*/ -void xbt_dict_print(void *data); -/* To dump multicache, this one dumps a string */ -void xbt_dict_prints(void *data); + + xbt_error_t xbt_dict_cursor_get_key (xbt_dict_cursor_t cursor, + /*OUT*/char **key); + xbt_error_t xbt_dict_cursor_get_data (xbt_dict_cursor_t cursor, + /*OUT*/void **data); + + void xbt_dict_cursor_first (const xbt_dict_t dict, + xbt_dict_cursor_t *cursor); + void xbt_dict_cursor_step (xbt_dict_cursor_t cursor); + int xbt_dict_cursor_get_or_free (xbt_dict_cursor_t *cursor, + char **key, + void **data); + /** \brief toto + \hideinitializer */ +# define xbt_dict_foreach(dict,cursor,key,data) \ + for (cursor=NULL, xbt_dict_cursor_first((dict),&(cursor)) ; \ + xbt_dict_cursor_get_or_free(&(cursor),&(key),(void**)(&data));\ + xbt_dict_cursor_step(cursor) ) + +/** @} */ +/** @} */ + +#if 0 + + MULTI-DICTS ARE BROKEN /*####[ Multi cache functions ]##############################################*/ /* The are cache of cache of data. Any function there works the same way */ /* than their simple cache counterpart. */ /*###############################"###########################################*/ +/* To dump multicache, this function dumps a cache */ +void xbt_dict_print(void *data); +/* To dump multicache, this one dumps a string */ +void xbt_dict_prints(void *data); /*----[ xbt_multidict_free ]------------------------------------------------*/ /* This function does not exist. Use xbt_dict_free instead. */ @@ -113,36 +184,7 @@ xbt_error_t xbt_multidict_remove(xbt_dict_t head, xbt_error_t xbt_multidict_remove_ext(xbt_dict_t head, int keycount,const char **key,int *key_len); - -/*####[ Cache cursor functions ]#############################################*/ -/* To traverse (simple) caches */ -/* Don't add or remove entries to the cache while traversing !!! */ -/*###########################################################################*/ -typedef struct xbt_dict_cursor_ *xbt_dict_cursor_t; -/* creator/destructor */ -xbt_dict_cursor_t xbt_dict_cursor_new(const xbt_dict_t head); -void xbt_dict_cursor_free(xbt_dict_cursor_t *cursor); - -/* back to first element - it is not enough to reinit the cache after an add/remove in cache*/ -void xbt_dict_cursor_rewind(xbt_dict_cursor_t cursor); - - -xbt_error_t xbt_dict_cursor_get_key (xbt_dict_cursor_t cursor, - /*OUT*/char **key); -xbt_error_t xbt_dict_cursor_get_data (xbt_dict_cursor_t cursor, - /*OUT*/void **data); - -void xbt_dict_cursor_first (const xbt_dict_t dict, - xbt_dict_cursor_t *cursor); -void xbt_dict_cursor_step (xbt_dict_cursor_t cursor); -int xbt_dict_cursor_get_or_free (xbt_dict_cursor_t *cursor, - char **key, - void **data); -#define xbt_dict_foreach(dict,cursor,key,data) \ - for (cursor=NULL, xbt_dict_cursor_first((dict),&(cursor)) ; \ - xbt_dict_cursor_get_or_free(&(cursor),&(key),(void**)(&data));\ - xbt_dict_cursor_step(cursor) ) +#endif END_DECL() diff --git a/include/xbt/error.h b/include/xbt/error.h index d35289a615..08647392a0 100644 --- a/include/xbt/error.h +++ b/include/xbt/error.h @@ -21,11 +21,22 @@ BEGIN_DECL() -void xbt_abort(void) _XBT_GNUC_NORETURN; +#define _XBT_ERR_PRE do { +#define _XBT_ERR_POST(code) \ + return code; \ +} while (0) -/**\brief Error types - \ingroup XBT_error -*/ +/** @addtogroup XBT_error + * @{*/ + +/** \brief Kill the programm in silence */ +void xbt_abort(void) _XBT_GNUC_NORETURN; + +/** \brief Kill the programm with an error message */ +void xbt_die(const char *msg) _XBT_GNUC_NORETURN; + + +/** \brief Error types */ typedef enum { no_error=0, /**< succes */ mismatch_error=1, /**< The provided ID does not match */ @@ -47,24 +58,46 @@ typedef enum { const char *xbt_error_name(xbt_error_t errcode); -#define TRY(a) do { \ - if ((errcode=a) != no_error) { \ +/** @name TRY macro family + * + * Those functions are used to launch a function call and react automatically + * to its return value. They expect such a variable to be declared in the scope: + * \verbatim xbt_error_t errcode;\endverbatim + * @{ + */ + +/** @brief return the error code if != no_error + * @hideinitializer + */ +#define TRY(action) do { \ + if ((errcode=action) != no_error) { \ fprintf (stderr, "%s:%d: '%s' error raising...\n", \ __FILE__,__LINE__, \ - xbt_error_name(errcode)); \ + xbt_error_name(errcode)); \ return errcode; \ } } while (0) -#define TRYCATCH(a,b) if ((errcode=a) != no_error && errcode !=b) return errcode -#define TRYFAIL(a) do { \ - if ((errcode=a) != no_error) { \ +/** @brief return the error code if != no_error and != \a catched + * @hideinitializer + */ +#define TRYCATCH(action,catched) if ((errcode=action) != no_error && errcode !=catched) return errcode + +/** @brief xbt_abort if the error code != no_error + * @hideinitializer + */ +#define TRYFAIL(action) do { \ + if ((errcode=action) != no_error) { \ fprintf(stderr,"%s:%d: Got '%s' error !\n", \ __FILE__,__LINE__, \ - xbt_error_name(errcode)); \ + xbt_error_name(errcode)); \ fflush(stdout); \ - xbt_abort(); \ + xbt_abort(); \ } } while(0) + +/** @brief return the error code if != \a expected_error (no_error not ok) + * @hideinitializer + */ #define TRYEXPECT(action,expected_error) do { \ errcode=action; \ if (errcode != expected_error) { \ @@ -75,74 +108,59 @@ const char *xbt_error_name(xbt_error_t errcode); } \ } while(0) -/* FIXME TRYCLEAN should be avoided for readability */ -#define TRYCLEAN(action,cleanup) do { \ - if ((errcode=action) != no_error) { \ - cleanup; \ - return errcode; \ - } \ -} while(0) - -#if 0 /* FIXME: We don't use backtrace. Drop it? */ -#define _XBT_ERR_PRE do { \ - void *_gs_array[30]; \ - size_t _gs_size= backtrace (_gs_array, 30); \ - char **_gs_strings= backtrace_symbols (_gs_array, _gs_size); \ - size_t _gs_i; - -#define _XBT_ERR_POST(code) \ - fprintf(stderr,"Backtrace follows\n"); \ - for (_gs_i = 0; _gs_i < _gs_size; _gs_i++) \ - fprintf (stderr," %s\n", _gs_strings[_gs_i]); \ - return code; \ -} while (0) - -#else /* if 0 */ -#define _XBT_ERR_PRE do { -#define _XBT_ERR_POST(code) \ - return code; \ -} while (0) -#endif +/** @}*/ +/** @name RAISE macro family + * + * Return a error code, doing some logs on stderr. + * + * @{ + */ +/** @hideinitializer */ #define RAISE0(code,fmt) _XBT_ERR_PRE \ fprintf(stderr,"%s:%d:%s: " fmt "\n", \ __FILE__,__LINE__,__FUNCTION__); \ _XBT_ERR_POST(code) +/** @hideinitializer */ #define RAISE1(code,fmt,a1) _XBT_ERR_PRE \ fprintf(stderr,"%s:%d:%s: " fmt "\n", \ __FILE__,__LINE__,__FUNCTION__,a1); \ _XBT_ERR_POST(code) +/** @hideinitializer */ #define RAISE2(code,fmt,a1,a2) _XBT_ERR_PRE \ fprintf(stderr,"%s:%d:%s: " fmt "\n", \ __FILE__,__LINE__,__FUNCTION__,a1,a2); \ _XBT_ERR_POST(code) +/** @hideinitializer */ #define RAISE3(code,fmt,a1,a2,a3) _XBT_ERR_PRE \ fprintf(stderr,"%s:%d:%s: " fmt "\n", \ __FILE__,__LINE__,__FUNCTION__,a1,a2,a3); \ _XBT_ERR_POST(code) +/** @hideinitializer */ #define RAISE4(code,fmt,a1,a2,a3,a4) _XBT_ERR_PRE \ fprintf(stderr,"%s:%d:%s: " fmt "\n", \ __FILE__,__LINE__,__FUNCTION__,a1,a2,a3,a4); \ _XBT_ERR_POST(code) +/** @hideinitializer */ #define RAISE5(code,fmt,a1,a2,a3,a4,a5) _XBT_ERR_PRE \ fprintf(stderr,"%s:%d:%s: " fmt "\n", \ __FILE__,__LINE__,__FUNCTION__,a1,a2,a3,a4,a5); \ _XBT_ERR_POST(code) +/** @hideinitializer */ #define RAISE6(code,fmt,a1,a2,a3,a4,a5,a6) _XBT_ERR_PRE \ fprintf(stderr,"%s:%d:%s: " fmt "\n", \ __FILE__,__LINE__,__FUNCTION__,a1,a2,a3,a4,a5,a6); \ _XBT_ERR_POST(code) -/* #define RAISE_MALLOC RAISE0(malloc_error,"Malloc error") */ -#define RAISE_IMPOSSIBLE RAISE0(unknown_error,"The Impossible did happen") -#define RAISE_UNIMPLEMENTED RAISE1(unknown_error,"Function %s unimplemented",__FUNCTION__) - +/**@}*/ /** - * \name Asserts - * \ingroup XBT_error - * asserts and stuff + * \name assert macro familly + * + * Those are the GRAS version of the good ol' assert macro. You can pass them a format message and + * arguments, just as if it where a printf. + * + * @{ */ -/*@{*/ #ifdef NDEBUG #define xbt_assert(cond) #define xbt_assert0(cond,msg) @@ -153,26 +171,39 @@ const char *xbt_error_name(xbt_error_t errcode); #define xbt_assert5(cond,msg,a,b,c,d,e) #define xbt_assert6(cond,msg,a,b,c,d,e,f) #else +/** @hideinitializer */ #define xbt_assert(cond) if (!(cond)) { CRITICAL1("Assertion %s failed", #cond); xbt_abort(); } +/** @hideinitializer */ #define xbt_assert0(cond,msg) if (!(cond)) { CRITICAL0(msg); xbt_abort(); } +/** @hideinitializer */ #define xbt_assert1(cond,msg,a) if (!(cond)) { CRITICAL1(msg,a); xbt_abort(); } +/** @hideinitializer */ #define xbt_assert2(cond,msg,a,b) if (!(cond)) { CRITICAL2(msg,a,b); xbt_abort(); } +/** @hideinitializer */ #define xbt_assert3(cond,msg,a,b,c) if (!(cond)) { CRITICAL3(msg,a,b,c); xbt_abort(); } +/** @hideinitializer */ #define xbt_assert4(cond,msg,a,b,c,d) if (!(cond)) { CRITICAL4(msg,a,b,c,d); xbt_abort(); } +/** @hideinitializer */ #define xbt_assert5(cond,msg,a,b,c,d,e) if (!(cond)) { CRITICAL5(msg,a,b,c,d,e); xbt_abort(); } +/** @hideinitializer */ #define xbt_assert6(cond,msg,a,b,c,d,e,f) if (!(cond)) { CRITICAL6(msg,a,b,c,d,e,f); xbt_abort(); } #endif -/*@}*/ -/** - * \brief How to abort with an error message - * \ingroup XBT_error +/** @}*/ + +/** @name Useful predefined errors + * + * @{ */ -void xbt_die(const char *msg) _XBT_GNUC_NORETURN; +#define RAISE_IMPOSSIBLE RAISE0(unknown_error,"The Impossible did happen") +#define RAISE_UNIMPLEMENTED RAISE1(unknown_error,"Function %s unimplemented",__FUNCTION__) #define DIE_IMPOSSIBLE xbt_assert0(0,"The Impossible did happen (yet again)") #define xbt_assert_error(a) xbt_assert1(errcode == (a), "Error %s unexpected",xbt_error_name(errcode)) +/** @}*/ +/**@}*/ + END_DECL() #endif /* XBT_ERROR_H */ diff --git a/src/xbt/dict.c b/src/xbt/dict.c index d541f051fd..2f4e3a8ab5 100644 --- a/src/xbt/dict.c +++ b/src/xbt/dict.c @@ -14,11 +14,6 @@ #include -/** \defgroup XBT_dict A generic dictionnary - * \brief This section describes the API to a dictionnary structure - * that associates as string to a void* key. It is not a hash table - * and the internal data-structure rather looks like a tree. - */ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dict,xbt, "Dictionaries provide the same functionnalities than hash tables"); @@ -27,9 +22,8 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(dict,xbt, /*####[ Code ]###############################################################*/ /** - * \ingroup XBT_dict - * - * \return pointer to the destination + * @brief Constructor + * @return pointer to the destination * * Creates and initialize a new dictionnary */ @@ -40,8 +34,8 @@ xbt_dict_new(void) { return res; } /** - * \ingroup XBT_dict - * \param dict the dictionnary to be freed + * @brief Destructor + * @param dict the dictionnary to be freed * * Frees a cache structure with all its childs. */ @@ -58,17 +52,16 @@ xbt_dict_free(xbt_dict_t *dict) { } /** - * \ingroup XBT_dict - * + * \brief Add data to the dict (arbitrary key) * \param dict the container * \param key the key to set the new data - * \param key_len the size of the #key + * \param key_len the size of the \a key * \param data the data to add in the dict - * \param free_ctn function to call with (#key as argument) when - * #key is removed from the dictionnary + * \param free_ctn function to call with (\a key as argument) when + * \a key is removed from the dictionnary * - * set the #data in the structure under the #key, which can be any kind - * of data, as long as its length is provided in #key_len. + * set the \a data in the structure under the \a key, which can be any kind + * of data, as long as its length is provided in \a key_len. */ void xbt_dict_set_ext(xbt_dict_t dict, @@ -84,15 +77,15 @@ xbt_dict_set_ext(xbt_dict_t dict, } /** - * \ingroup XBT_dict + * \brief Add data to the dict (null-terminated key) * * \param dict the head of the dict * \param key the key to set the new data * \param data the data to add in the dict - * \param free_ctn function to call with (#key as argument) when - * #key is removed from the dictionnary + * \param free_ctn function to call with (\a key as argument) when + * \a key is removed from the dictionnary * - * set the #data in the structure under the #key, which is a + * set the \a data in the structure under the \a key, which is a * null terminated string. */ void @@ -107,15 +100,15 @@ xbt_dict_set(xbt_dict_t dict, } /** - * \ingroup XBT_dict + * \brief Retrieve data from the dict (arbitrary key) * * \param dict the dealer of data * \param key the key to find data - * \param key_len the size of the #key + * \param key_len the size of the \a key * \param data the data that we are looking for * \return xbt_error * - * Search the given #key. mismatch_error when not found. + * Search the given \a key. mismatch_error when not found. */ xbt_error_t xbt_dict_get_ext(xbt_dict_t dict, @@ -129,14 +122,14 @@ xbt_dict_get_ext(xbt_dict_t dict, } /** - * \ingroup XBT_dict + * \brief Retrieve data from the dict (null-terminated key) * * \param dict the dealer of data * \param key the key to find data * \param data the data that we are looking for * \return xbt_error * - * Search the given #key. mismatch_error when not found. + * Search the given \a key. mismatch_error when not found. */ xbt_error_t xbt_dict_get(xbt_dict_t dict, @@ -149,14 +142,14 @@ xbt_dict_get(xbt_dict_t dict, /** - * \ingroup XBT_dict + * \brief Remove data from the dict (arbitrary key) * * \param dict the trash can * \param key the key of the data to be removed - * \param key_len the size of the #key + * \param key_len the size of the \a key * \return xbt_error_t * - * Remove the entry associated with the given #key + * Remove the entry associated with the given \a key */ xbt_error_t xbt_dict_remove_ext(xbt_dict_t dict, @@ -168,13 +161,12 @@ xbt_dict_remove_ext(xbt_dict_t dict, } /** - * \ingroup XBT_dict + * \brief Remove data from the dict (null-terminated key) * * \param dict the head of the dict * \param key the key of the data to be removed - * \return xbt_error_t * - * Remove the entry associated with the given #key + * Remove the entry associated with the given \a key */ xbt_error_t xbt_dict_remove(xbt_dict_t dict, @@ -187,14 +179,13 @@ xbt_dict_remove(xbt_dict_t dict, /** - * \ingroup XBT_dict + * \brief Outputs the content of the structure (debuging purpose) * * \param dict the exibitionist * \param output a function to dump each data in the tree - * \return xbt_error_t * - * Ouputs the content of the structure. (for debuging purpose). #ouput is a - * function to output the data. If NULL, data won't be displayed. + * Ouputs the content of the structure. (for debuging purpose). \a ouput is a + * function to output the data. If NULL, data won't be displayed, just the tree structure. */ void diff --git a/src/xbt/dict_cursor.c b/src/xbt/dict_cursor.c index d75e811870..3dc52dc01a 100644 --- a/src/xbt/dict_cursor.c +++ b/src/xbt/dict_cursor.c @@ -36,13 +36,8 @@ _cursor_push_keys(xbt_dict_cursor_t p_cursor, #undef xbt_dict_CURSOR_DEBUG /*#define xbt_dict_CURSOR_DEBUG 1*/ -/** - * xbt_dict_cursor_new: - * - * @head: the head of the dict - * @cursor: the curent position in the dict - * - * Structure creator +/** @brief Creator + * @param head the dict */ xbt_dict_cursor_t xbt_dict_cursor_new(const xbt_dict_t head) { @@ -61,11 +56,8 @@ xbt_dict_cursor_new(const xbt_dict_t head) { } /** - * xbt_dict_cursor_free: - * - * @cursor: poor victim - * - * Structure destructor + * @brief Destructor + * @param cursor poor victim */ void xbt_dict_cursor_free(xbt_dict_cursor_t *cursor) { @@ -77,9 +69,7 @@ xbt_dict_cursor_free(xbt_dict_cursor_t *cursor) { } } -/** - * __cursor_not_null: - * +/* * Sanity check to see if the head contains something */ static _XBT_INLINE @@ -120,13 +110,7 @@ _cursor_push_keys(xbt_dict_cursor_t cursor, CDEBUG1(dict_cursor, "Count = %d", count); } -/** - * xbt_dict_cursor_rewind: - * @cursor: the cursor - * @Returns: xbt_error_t - * - * back to the first element - */ +/** @brief Reinitialize the cursor. Mandatory after removal or add in dict. */ void xbt_dict_cursor_rewind(xbt_dict_cursor_t cursor) { @@ -147,11 +131,10 @@ xbt_dict_cursor_rewind(xbt_dict_cursor_t cursor) { } /** - * xbt_dict_cursor_first: - * @dict: on what to let the cursor iterate - * @cursor: dest address + * @brief Create the cursor if it does not exists. Rewind it in any case. * - * Create the cursor if it does not exists. Rewind it in any case. + * @param dict on what to let the cursor iterate + * @param[out] cursor dest address */ void xbt_dict_cursor_first (const xbt_dict_t dict, xbt_dict_cursor_t *cursor){ @@ -166,10 +149,7 @@ void xbt_dict_cursor_first (const xbt_dict_t dict, /** - * xbt_dict_cursor_step: - * @cursor: the cursor - * - * Move to the next element. + * \brief Move to the next element. */ void xbt_dict_cursor_step(xbt_dict_cursor_t cursor) { @@ -180,11 +160,9 @@ xbt_dict_cursor_step(xbt_dict_cursor_t cursor) { } /** - * xbt_dict_cursor_get_or_free: - * @cursor: the cursor - * @Returns: true if it's ok, false if there is no more data + * @brief Get current data, or free the cursor if there is no data left * - * Get current data + * @returns true if it's ok, false if there is no more data */ int xbt_dict_cursor_get_or_free(xbt_dict_cursor_t *cursor, @@ -218,12 +196,9 @@ xbt_dict_cursor_get_or_free(xbt_dict_cursor_t *cursor, } /** - * xbt_dict_cursor_get_key: - * @cursor: the cursor - * @key: the current element - * @Returns: xbt_error_t - * - * Get current key + * @brief Get current key + * @param cursor: the cursor + * @param key where to put the key */ xbt_error_t xbt_dict_cursor_get_key(xbt_dict_cursor_t cursor, @@ -238,10 +213,9 @@ xbt_dict_cursor_get_key(xbt_dict_cursor_t cursor, } /** - * xbt_dict_cursor_get_data: - * @cursor: the cursor - * - * Get current data + * @brief Get current data + * @param cursor the cursor + * @param data where to put the data */ xbt_error_t xbt_dict_cursor_get_data(xbt_dict_cursor_t cursor, diff --git a/src/xbt/error.c b/src/xbt/error.c index 765145c81a..907a1af8df 100644 --- a/src/xbt/error.c +++ b/src/xbt/error.c @@ -9,13 +9,10 @@ under the terms of the license (GNU LGPL) which comes with this package. */ #include "xbt/error.h" -/** \defgroup XBT_error Error tracking support - * \brief This section describes a set of macros used to handle errors easily. - */ /** * \brief Usefull to do nice error repporting messages. - * \ingroup XBT_error + * * \param errcode * \return the printable name of an error code * @@ -40,7 +37,7 @@ XBT_LOG_EXTERNAL_CATEGORY(xbt); XBT_LOG_DEFAULT_CATEGORY(xbt); /** - * \ingroup XBT_error + * @brief Kill the prog * \param msg * * Things are so messed up that the only thing to do now, is to stop the program. @@ -49,4 +46,3 @@ void xbt_die (const char *msg) { CRITICAL1("%s",msg); xbt_abort(); } - diff --git a/src/xbt/log.c b/src/xbt/log.c index 00d69f0f96..2a4b4e5b44 100644 --- a/src/xbt/log.c +++ b/src/xbt/log.c @@ -18,8 +18,7 @@ #include "xbt/error.h" #include "xbt/dynar.h" -/** \defgroup XBT_log Logging support - * \brief A generic logging facility in the spirit of log4j +/** \addtogroup XBT_log * * This section describes the API to the log functions used * everywhere in this project. -- 2.20.1