From 215ed67257173f5e26c9489ec96c4ced08d1614a Mon Sep 17 00:00:00 2001 From: mquinson Date: Sat, 22 Oct 2005 14:23:47 +0000 Subject: [PATCH] XBT documentation reorganization. module-xbt only contains the structure, module documentation moved to header files (even the @brief field); change @name to @defgroup; add navbars all over the place git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@1793 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- include/xbt/asserts.h | 11 ++++- include/xbt/config.h | 98 +++++++++++++++++++++++++++---------------- include/xbt/dict.h | 58 +++++++++++++++++-------- include/xbt/dynar.h | 59 ++++++++++++++++++++++---- include/xbt/ex.h | 68 ++++++++++++++++++++++++------ include/xbt/fifo.h | 51 ++++++++++++++++------ include/xbt/heap.h | 4 ++ include/xbt/log.h | 25 +++++++++++ include/xbt/set.h | 31 +++++++++++--- include/xbt/swag.h | 51 +++++++++++++++------- include/xbt/sysdep.h | 11 +++-- 11 files changed, 357 insertions(+), 110 deletions(-) diff --git a/include/xbt/asserts.h b/include/xbt/asserts.h index ac757041b2..df2d1f232f 100644 --- a/include/xbt/asserts.h +++ b/include/xbt/asserts.h @@ -14,7 +14,16 @@ SG_BEGIN_DECL() /** - * \addtogroup XBT_error + * @addtogroup XBT_error + * @brief Those are the SimGrid version of the good ol' assert macro. + * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_log] + *
Next [\ref XBT_config]
+ * + * You can pass them a format message and arguments, just as if it where a printf. + * It is converted to a CRITICALn logging request. + * * @{ */ #ifdef NDEBUG diff --git a/include/xbt/config.h b/include/xbt/config.h index dfd08b24e7..b22da93583 100644 --- a/include/xbt/config.h +++ b/include/xbt/config.h @@ -17,7 +17,13 @@ SG_BEGIN_DECL() /** @addtogroup XBT_config - * + * @brief Changing the configuration of SimGrid components (grounding feature) + * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_error] + *
Next [\ref XBT_dynar] + *
Down [\ref XBT_cfg_use]
+ * * All modules of the SimGrid toolkit can be configured with this API. * User modules and libraries can also use these facilities to handle * their own configuration. @@ -45,7 +51,8 @@ SG_BEGIN_DECL() * * \todo This great mechanism is not used in SimGrid yet... * - * \section XBT_cfg_ex Example + * + * \section XBT_cfg_ex Example of use * * \dontinclude config_usage.c * @@ -69,40 +76,15 @@ SG_BEGIN_DECL() * unregistered variable. * \skip myset * \until cfg_free - * @{ + * */ -/** @name 1. Type declaration and memory management - * - * +/** @defgroup XBT_cfg_use User interface: changing values + * @ingroup XBT_config * - * @{ - */ - /** @brief Configuration set are only special dynars. But don't rely on it, it may change. */ - typedef xbt_dynar_t xbt_cfg_t; - - /** @brief possible content of each configuration cell */ - typedef enum { - xbt_cfgelm_int=0, /**< int */ - xbt_cfgelm_double, /**< double */ - xbt_cfgelm_string, /**< char* */ - xbt_cfgelm_host, /**< both a char* (representing the hostname) and an integer (representing the port) */ - - xbt_cfgelm_any, /* not shown to users to prevent errors */ - xbt_cfgelm_type_count - } e_xbt_cfgelm_type_t; - - /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */ - typedef void (*xbt_cfg_cb_t)(const char*, int); - - xbt_cfg_t xbt_cfg_new (void); - void xbt_cfg_cpy(xbt_cfg_t tocopy, /* OUT */ xbt_cfg_t *whereto); - void xbt_cfg_free(xbt_cfg_t *cfg); - void xbt_cfg_dump(const char *name,const char*indent,xbt_cfg_t cfg); - - /** @} */ - -/** @name 2. User interface: changing values + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_config] + *
Prev + *
Next [\ref XBT_cfg_decl]
* * This is the only interface you should use unless you want to let your * own code become configurable with this. @@ -155,7 +137,46 @@ void xbt_cfg_rm_at (xbt_cfg_t cfg, const char *name, int pos); void xbt_cfg_empty(xbt_cfg_t cfg, const char *name); /* @} */ -/** @name 3. Registering stuff + +/** @defgroup XBT_cfg_decl Type declaration and memory management + * @ingroup XBT_config + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_config] + *
Prev [\ref XBT_cfg_use] + *
Next [\ref XBT_cfg_register]
+ * + * @{ + */ + /** @brief Configuration set are only special dynars. But don't rely on it, it may change. */ + typedef xbt_dynar_t xbt_cfg_t; + + /** @brief possible content of each configuration cell */ + typedef enum { + xbt_cfgelm_int=0, /**< int */ + xbt_cfgelm_double, /**< double */ + xbt_cfgelm_string, /**< char* */ + xbt_cfgelm_host, /**< both a char* (representing the hostname) and an integer (representing the port) */ + + xbt_cfgelm_any, /* not shown to users to prevent errors */ + xbt_cfgelm_type_count + } e_xbt_cfgelm_type_t; + + /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */ + typedef void (*xbt_cfg_cb_t)(const char*, int); + + xbt_cfg_t xbt_cfg_new (void); + void xbt_cfg_cpy(xbt_cfg_t tocopy, /* OUT */ xbt_cfg_t *whereto); + void xbt_cfg_free(xbt_cfg_t *cfg); + void xbt_cfg_dump(const char *name,const char*indent,xbt_cfg_t cfg); + + /** @} */ + +/** @defgroup XBT_cfg_register Registering stuff + * @ingroup XBT_config + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_config] + *
Prev [\ref XBT_cfg_decl] + *
Next [\ref XBT_cfg_get]
* * This how to add new variables to an existing configuration set. Use it to make your code * configurable. @@ -171,7 +192,12 @@ void xbt_cfg_empty(xbt_cfg_t cfg, const char *name); void xbt_cfg_check(xbt_cfg_t cfg); e_xbt_cfgelm_type_t xbt_cfg_get_type(xbt_cfg_t cfg, const char *name); /* @} */ -/** @name 4. Getting the stored values +/** @defgroup XBT_cfg_get Getting the stored values + * @ingroup XBT_config + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_config] + *
Prev [\ref XBT_cfg_register] + *
Next
* * This is how to retrieve the values stored in the configuration set. This is only * intended to configurable code, naturally. @@ -196,7 +222,7 @@ void xbt_cfg_empty(xbt_cfg_t cfg, const char *name); void xbt_cfg_get_host_at (xbt_cfg_t cfg, const char *name, int pos, char **host, int *port); /** @} */ -/** @} */ + SG_END_DECL() #endif /* _XBT_CONFIG_H_ */ diff --git a/include/xbt/dict.h b/include/xbt/dict.h index 3c0f80ea36..daa0a4cef5 100644 --- a/include/xbt/dict.h +++ b/include/xbt/dict.h @@ -17,6 +17,12 @@ SG_BEGIN_DECL() /** @addtogroup XBT_dict + * @brief The dictionnary data structure (comparable to hash tables) + * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_dynar] + *
Next [\ref XBT_set] + *
Down [\ref XBT_dict_cons]
* * This section describes the API to a dictionnary structure that * associates as string to a void* key. Even if it provides the same @@ -34,18 +40,16 @@ SG_BEGIN_DECL() 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 - * - * @{ -*/ + */ -/** @name 1. Constructor/destructor - * @{ +/** @defgroup XBT_dict_cons Dict constructor and destructor + * @ingroup XBT_dict + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dict] + *
Prev + *
Next [\ref XBT_dict_basic]
+ * + * @{ */ /** \brief Dictionnary data type (opaque structure) */ @@ -54,11 +58,17 @@ SG_BEGIN_DECL() void xbt_dict_free(xbt_dict_t *dict); /** @} */ -/** @name 2. Dictionnaries basic usage +/** @defgroup XBT_dict_basic Dictionnaries basic usage + * @ingroup XBT_dict + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dict] + *
Prev [\ref XBT_dict_cons] + *
Next [\ref XBT_dict_nnul]
* * 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); void *xbt_dict_get(xbt_dict_t head,const char *key); @@ -68,7 +78,12 @@ SG_BEGIN_DECL() void xbt_dict_dump(xbt_dict_t head,void (*output)(void*)); /** @} */ -/** @name 3. Non-null terminated keys +/** @defgroup XBT_dict_nnul Dictionnaries with non-nul terminated keys + * @ingroup XBT_dict + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dict] + *
Prev [\ref XBT_dict_basic] + *
Next [\ref XBT_dict_curs]
* * Those functions work even with non-null terminated keys. * @@ -83,7 +98,12 @@ SG_BEGIN_DECL() /** @} */ -/** @name 4. Cursors on dictionnaries +/** @defgroup XBT_dict_curs Cursors on dictionnaries + * @ingroup XBT_dict + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dict] + *
Prev [\ref XBT_dict_nnul] + *
Next [\ref XBT_dict_multi]
* * Don't get impressed, there is a lot of functions here, but traversing a * dictionnary is imediate with the xbt_dict_foreach macro. @@ -128,7 +148,12 @@ SG_BEGIN_DECL() xbt_dict_cursor_step(cursor) ) /** @} */ -/** @name 5. Multi-dictionnary +/** @defgroup XBT_dict_multi Multi-level dictionnaries + * @ingroup XBT_dict + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dict] + *
Prev [\ref XBT_dict_curs] + *
Next
* * They can be seen as dictionnary of multiple keys or as dictionnary of * dictionnary of ... of data. Most of the functions here work the same way @@ -165,7 +190,6 @@ void *xbt_multidict_get_ext(xbt_dict_t mdict, xbt_dynar_t keys, xbt_dynar_t lens void xbt_multidict_remove(xbt_dict_t mdict, xbt_dynar_t keys); void xbt_multidict_remove_ext(xbt_dict_t mdict, xbt_dynar_t keys, xbt_dynar_t lens); -/** @} */ /** @} */ SG_END_DECL() diff --git a/include/xbt/dynar.h b/include/xbt/dynar.h index 2b5fa44ac3..2cc56aa135 100644 --- a/include/xbt/dynar.h +++ b/include/xbt/dynar.h @@ -14,7 +14,15 @@ SG_BEGIN_DECL() -/** \addtogroup XBT_dynar +/** @addtogroup XBT_dynar + * @brief DynArr are dynamically sized vector which may contain any type of variables. + * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_config] + *
Next [\ref XBT_dict] + *
Down [\ref XBT_dynar_cons]
+ * + * These are the SimGrid version of the dynamically size arrays, which all C programmer recode one day or another. * * For performance concerns, the content of DynArr must be homogeneous (in * contrary to dictionnaries -- see the \ref XBT_dict section). You thus @@ -47,10 +55,16 @@ SG_BEGIN_DECL() * \until dynar_free * \skip xbt_exit * \until } - * @{ + * */ -/** @name 1. Constructor/destructor +/** @defgroup XBT_dynar_cons Dynar constructor and destructor + * @ingroup XBT_dynar + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dynar] + *
Prev + *
Next [\ref XBT_dynar_array]
+ * * @{ */ /** \brief Dynar data type (opaque type) */ @@ -68,7 +82,13 @@ SG_BEGIN_DECL() void xbt_dynar_dump(xbt_dynar_t dynar); /** @} */ -/** @name 2. regular array functions +/** @defgroup XBT_dynar_array Dynar as a regular array + * @ingroup XBT_dynar + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dynar] + *
Prev [\ref XBT_dynar_cons] + *
Next [\ref XBT_dynar_perl]
+ * * @{ */ @@ -81,7 +101,13 @@ SG_BEGIN_DECL() void xbt_dynar_remove_at(xbt_dynar_t dynar, int idx, void * const dst); /** @} */ -/** @name 2. Perl-like functions +/** @defgroup XBT_dynar_perl Perl-like use of dynars + * @ingroup XBT_dynar + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dynar] + *
Prev [\ref XBT_dynar_array] + *
Next [\ref XBT_dynar_ctn]
+ * * @{ */ @@ -92,7 +118,12 @@ SG_BEGIN_DECL() void xbt_dynar_map (const xbt_dynar_t dynar, void_f_pvoid_t *op); /** @} */ -/** @name 3. Manipulating pointers to the content +/** @defgroup XBT_dynar_ctn Direct manipulation to the dynars content + * @ingroup XBT_dynar + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dynar] + *
Prev [\ref XBT_dynar_perl] + *
Next [\ref XBT_dynar_speed]
* * Those functions do not retrive the content, but only their address. * @@ -105,7 +136,12 @@ SG_BEGIN_DECL() void *xbt_dynar_pop_ptr(xbt_dynar_t dynar); /** @} */ -/** @name 4. Speed optimized functions for scalars +/** @defgroup XBT_dynar_speed Speed optimized access to dynars of scalars + * @ingroup XBT_dynar + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dynar] + *
Prev [\ref XBT_dynar_ctn] + *
Next [\ref XBT_dynar_cursor]
* * While the other functions use a memcpy to retrive the content into the * user provided area, those ones use a regular affectation. It only works @@ -132,7 +168,12 @@ SG_BEGIN_DECL() *(type*)xbt_dynar_pop_ptr(dynar) /** @} */ -/** @name 5. Cursors on DynArr +/** @defgroup XBT_dynar_cursor Cursors on dynar + * @ingroup XBT_dynar + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_dynar] + *
Prev [\ref XBT_dynar_speed] + *
Next
* * Cursors are used to iterate over the structure. Never add elements to the * DynArr during the traversal. To remove elements, use the @@ -171,8 +212,8 @@ xbt_dynar_foreach (dyn,cpt,str) { xbt_dynar_cursor_get(_dynar,&(_cursor),&_data) ; \ xbt_dynar_cursor_step(_dynar,&(_cursor)) ) +/** @} */ SG_END_DECL() -/* @} */ #endif /* _XBT_DYNAR_H */ diff --git a/include/xbt/ex.h b/include/xbt/ex.h index cd66c738ab..f1bc41c884 100644 --- a/include/xbt/ex.h +++ b/include/xbt/ex.h @@ -70,6 +70,11 @@ extern int backtrace (void **__array, int __size); typedef struct { __ex_mctx_struct } __ex_mctx_t; /** @addtogroup XBT_ex + * @brief A set of macros providing exception a la C++ in ANSI C (grounding feature) + * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_syscall] + *
Next [\ref XBT_log]
* * This module is a small ISO-C++ style exception handling library * for use in the ISO-C language. It allows you to use the paradigm @@ -87,9 +92,15 @@ typedef struct { __ex_mctx_struct } __ex_mctx_t; * These features are brought to you by a modified version of the libex * library, one of the numerous masterpiece of Ralf S. Engelschall. * + * @section XBT_ex_toc TABLE OF CONTENTS + * + * - \ref XBT_ex_intro + * - \ref XBT_ex_base + * - \ref XBT_ex_pitfalls + * * @section XBT_ex_intro DESCRIPTION * - * In SimGrid, exceptions is a triple <\a msg , \a category , \a value> + * In SimGrid, an exception is a triple <\a msg , \a category , \a value> * where \a msg is a human-readable text describing the exceptional * condition, \a code an integer describing what went wrong and \a value * providing a sort of sub-category. (this is different in the original libex). @@ -307,15 +318,17 @@ extern void __xbt_ex_terminate_default(xbt_ex_t *e); if (1) { \ if (1) +#ifndef DOXYGEN_SKIP +# ifdef __cplusplus +# define XBT_EX_T_CPLUSPLUSCAST (xbt_ex_t&) +# else +# define XBT_EX_T_CPLUSPLUSCAST +# endif +#endif + /** @brief the block for catching (ie, deal with) an exception * @hideinitializer */ -#ifdef __cplusplus -# define XBT_EX_T_CPLUSPLUSCAST (xbt_ex_t&) -#else -# define XBT_EX_T_CPLUSPLUSCAST -#endif - #define CATCH(e) \ else { \ } \ @@ -334,7 +347,7 @@ extern void __xbt_ex_terminate_default(xbt_ex_t *e); } \ else -/** @brief Build an exception from the supplied arguments and throws it +/** @brief Helper macro for THROWS0-6 * @hideinitializer * * @param c: category code (integer) @@ -372,12 +385,26 @@ extern void __xbt_ex_terminate_default(xbt_ex_t *e); abort();/* nope, stupid GCC, we won't survive a THROW (this won't be reached) */ \ } while (0) +/** @brief Builds and throws an exception with a string taking no arguments + @hideinitializer */ #define THROW0(c,v,m) _THROW(c,v,(m?bprintf(m):NULL)) +/** @brief Builds and throws an exception with a string taking one argument + @hideinitializer */ #define THROW1(c,v,m,a1) _THROW(c,v,bprintf(m,a1)) +/** @brief Builds and throws an exception with a string taking two arguments + @hideinitializer */ #define THROW2(c,v,m,a1,a2) _THROW(c,v,bprintf(m,a1,a2)) +/** @brief Builds and throws an exception with a string taking three arguments + @hideinitializer */ #define THROW3(c,v,m,a1,a2,a3) _THROW(c,v,bprintf(m,a1,a2,a3)) +/** @brief Builds and throws an exception with a string taking four arguments + @hideinitializer */ #define THROW4(c,v,m,a1,a2,a3,a4) _THROW(c,v,bprintf(m,a1,a2,a3,a4)) +/** @brief Builds and throws an exception with a string taking five arguments + @hideinitializer */ #define THROW5(c,v,m,a1,a2,a3,a4,a5) _THROW(c,v,bprintf(m,a1,a2,a3,a4,a5)) +/** @brief Builds and throws an exception with a string taking six arguments + @hideinitializer */ #define THROW6(c,v,m,a1,a2,a3,a4,a5,a6) _THROW(c,v,bprintf(m,a1,a2,a3,a4,a5,a6)) #define THROW_IMPOSSIBLE THROW0(unknown_error,0,"The Impossible Did Happen (yet again)") @@ -396,11 +423,8 @@ extern void __xbt_ex_terminate_default(xbt_ex_t *e); abort();\ } while(0) -/** @brief like RETHROW, but adding some details to the message - * @hideinitializer - */ - +#ifndef DOXYGEN_SKIP #define _XBT_PRE_RETHROW \ do { \ char *_xbt_ex_internal_msg = __xbt_ex_ctx()->ctx_ex.msg; \ @@ -410,14 +434,34 @@ extern void __xbt_ex_terminate_default(xbt_ex_t *e); free(_xbt_ex_internal_msg); \ RETHROW; \ } while (0) +#endif +/** @brief like THROW0, but adding some details to the message of an existing exception + * @hideinitializer + */ #define RETHROW0(msg) _XBT_PRE_RETHROW msg, _XBT_POST_RETHROW +/** @brief like THROW1, but adding some details to the message of an existing exception + * @hideinitializer + */ #define RETHROW1(msg,a) _XBT_PRE_RETHROW msg,a, _XBT_POST_RETHROW +/** @brief like THROW2, but adding some details to the message of an existing exception + * @hideinitializer + */ #define RETHROW2(msg,a,b) _XBT_PRE_RETHROW msg,a,b, _XBT_POST_RETHROW +/** @brief like THROW3, but adding some details to the message of an existing exception + * @hideinitializer + */ #define RETHROW3(msg,a,b,c) _XBT_PRE_RETHROW msg,a,b,c, _XBT_POST_RETHROW +/** @brief like THROW4, but adding some details to the message of an existing exception + * @hideinitializer + */ #define RETHROW4(msg,a,b,c,d) _XBT_PRE_RETHROW msg,a,b,c, _XBT_POST_RETHROW +/** @brief like THROW5, but adding some details to the message of an existing exception + * @hideinitializer + */ #define RETHROW5(msg,a,b,c,d,e) _XBT_PRE_RETHROW msg,a,b,c,d,e _XBT_POST_RETHROW +/** @brief Exception destructor */ void xbt_ex_free(xbt_ex_t e); const char * xbt_ex_catname(xbt_errcat_t cat); diff --git a/include/xbt/fifo.h b/include/xbt/fifo.h index 004db05ddf..46becae17e 100644 --- a/include/xbt/fifo.h +++ b/include/xbt/fifo.h @@ -11,10 +11,24 @@ SG_BEGIN_DECL() -/** \addtogroup XBT_fifo - * @{ */ +/** @addtogroup XBT_fifo + * @brief This section describes the API to generic workqueue. + * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_set] + *
Next [\ref XBT_swag] + *
Down [\ref XBT_fifo_cons]
+ * + * These functions provide the same kind of functionnality as dynamic arrays but in time O(1). + * However these functions use malloc/free way too much often. + */ -/** @name 1. Constructor/destructor +/** @defgroup XBT_fifo_cons Fifo constructor and destructor + * @ingroup XBT_fifo + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_fifo] + *
Prev + *
Next [\ref XBT_fifo_perl]
* @{ */ @@ -30,7 +44,12 @@ xbt_fifo_t xbt_fifo_new(void); void xbt_fifo_free(xbt_fifo_t); /** @} */ -/** @name 2. Perl-like functions +/** @defgroup XBT_fifo_perl Fifo perl-like functions + * @ingroup XBT_fifo + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_fifo] + *
Prev [\ref XBT_fifo_cons] + *
Next [\ref XBT_fifo_direct]
* @{ */ xbt_fifo_item_t xbt_fifo_push(xbt_fifo_t, void *); @@ -41,7 +60,12 @@ int xbt_fifo_size(xbt_fifo_t); int xbt_fifo_is_in(xbt_fifo_t, void *); /** @} */ -/** @name 3. Manipulating items directly +/** @defgroup XBT_fifo_direct Direct access to fifo elements + * @ingroup XBT_fifo + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_fifo] + *
Prev [\ref XBT_fifo_perl] + *
Next [\ref XBT_fifo_misc]
* * @{ */ @@ -70,6 +94,7 @@ xbt_fifo_item_t xbt_fifo_get_prev_item(xbt_fifo_item_t i); * \param i a bucket (#xbt_fifo_item_t) * \param type a type * \param n an object of type \a type. + * @hideinitializer * * Iterates over the whole list. */ @@ -80,7 +105,12 @@ xbt_fifo_item_t xbt_fifo_get_prev_item(xbt_fifo_item_t i); /** @} */ -/** @name 4. Miscanaleous +/** @defgroup XBT_fifo_misc Misc fifo functions + * @ingroup XBT_fifo + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_fifo] + *
Prev [\ref XBT_fifo_direct] + *
Next
* * @{ */ @@ -88,19 +118,16 @@ void **xbt_fifo_to_array(xbt_fifo_t); xbt_fifo_t xbt_fifo_copy(xbt_fifo_t); /** @} */ -/** @name 5. Deprecated functions: don't use! - * - * @{ - */ +/* Deprecated functions: don't use! */ xbt_fifo_item_t xbt_fifo_newitem(void); void xbt_fifo_freeitem(xbt_fifo_item_t); xbt_fifo_item_t xbt_fifo_getFirstItem(xbt_fifo_t l); xbt_fifo_item_t xbt_fifo_getNextItem(xbt_fifo_item_t i); xbt_fifo_item_t xbt_fifo_getPrevItem(xbt_fifo_item_t i); -/** @} */ + SG_END_DECL() -/** @} */ + #endif /* _XBT_FIFO_H */ diff --git a/include/xbt/heap.h b/include/xbt/heap.h index 70dd7b7d0a..368107b283 100644 --- a/include/xbt/heap.h +++ b/include/xbt/heap.h @@ -12,7 +12,11 @@ #include "xbt/dynar.h" /* void_f_pvoid_t */ /** @addtogroup XBT_heap + * @brief This section describes the API to generic heap with O(log(n)) access. * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_swag] + *
Next
* @{ */ /* @brief heap datatype */ diff --git a/include/xbt/log.h b/include/xbt/log.h index 4f4c38be6f..54a77cb490 100644 --- a/include/xbt/log.h +++ b/include/xbt/log.h @@ -7,6 +7,31 @@ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ +/** @addtogroup XBT_log + * @brief A generic logging facility in the spirit of log4j (grounding feature) + * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_ex] + *
Next [\ref XBT_error] + *
Down [\ref XBT_log_cats]
+ * + */ + +/** \defgroup XBT_log_cats Existing log categories + * \ingroup XBT_log + * \brief (automatically extracted) + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_log]
+ * + * 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 ;) + */ + /* XBT_LOG_MAYDAY: define this to replace the logging facilities with basic printf function. Useful to debug the logging facilities themselves */ #undef XBT_LOG_MAYDAY diff --git a/include/xbt/set.h b/include/xbt/set.h index 47a4cc47fe..c62a835667 100644 --- a/include/xbt/set.h +++ b/include/xbt/set.h @@ -15,7 +15,13 @@ SG_BEGIN_DECL() /** @addtogroup XBT_set + * @brief A data container consisting in \ref XBT_dict and \ref XBT_dynar * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_dict] + *
Next [\ref XBT_fifo] + *
Down [\ref XBT_set_cons]
+ * * The elements stored in such a data structure can be retrieve both by * name and by ID. For this to work, the first fields of the structures * stored must begin with: @@ -29,11 +35,15 @@ SG_BEGIN_DECL() * Such a datastructure was necessary/useful to store the GRAS type * descriptions, but it should be reworked to become generic. * - * @{ -*/ + */ -/** @name 1. Set and set elements, constructor/destructor +/** @defgroup XBT_set_cons Set and set elements, constructor/destructor + * @ingroup XBT_set + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_set] + *
Prev + *
Next [\ref XBT_set_basic]
* * @{ */ @@ -53,7 +63,12 @@ void xbt_set_free(xbt_set_t *set); /** @} */ typedef struct xbt_set_elm_ s_xbt_set_elm_t; typedef struct xbt_set_elm_ * xbt_set_elm_t; -/** @name 2. Main functions +/** @defgroup XBT_set_basic Sets basic usage + * @ingroup XBT_set + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_set] + *
Prev [\ref XBT_set_cons] + *
Next [\ref XBT_set_curs]
* * @{ */ @@ -65,7 +80,12 @@ xbt_set_elm_t xbt_set_get_by_name_ext(xbt_set_t set, const char *key, int key_le xbt_set_elm_t xbt_set_get_by_id (xbt_set_t set, int id); /** @} */ -/** @name 3. Cursors +/** @defgroup XBT_set_curs Sets cursors + * @ingroup XBT_set + * + *
Top [\ref index]::[\ref XBT_API]::[\ref XBT_set] + *
Prev [\ref XBT_set_basic] + *
Next
* * \warning Don't add or remove entries to the cache while traversing * @@ -89,7 +109,6 @@ int xbt_set_cursor_get_or_free (xbt_set_cursor_t *cursor, xbt_set_cursor_get_or_free(&(cursor),(xbt_set_elm_t*)&(elm)); \ xbt_set_cursor_step(cursor) ) -/* @} */ /* @} */ SG_END_DECL() diff --git a/include/xbt/swag.h b/include/xbt/swag.h index de3090cb3f..be73804d75 100644 --- a/include/xbt/swag.h +++ b/include/xbt/swag.h @@ -15,26 +15,34 @@ #include "xbt/misc.h" #include "xbt/sysdep.h" -/* This type should be added to a type that is to be used in such a swag */ -/* Whenever a new object with this struct is created, all fields have - to be set to NULL */ /** - * \addtogroup XBT_swag + * @addtogroup XBT_swag + * @brief a O(1) set based on linked lists * + *
Top [\ref index]::[\ref XBT_API] + *
Prev [\ref XBT_fifo] + *
Next [\ref XBT_heap] + *
Down [\ref XBT_swag_type]
+ * * 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 + * cast and dirty things. So make sure you know what you are doing while using it. + * 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 +/** @defgroup XBT_swag_type Swag types + @ingroup XBT_swag +
Top [\ref index]::[\ref XBT_API]::[\ref XBT_swag] +
Prev +
Next [\ref XBT_swag_func]
+ Specific set. + These typedefs are public so that the compiler can do his job but believe me, you don't want to try to play with those structs directly. Use them as an abstract datatype. @@ -45,7 +53,11 @@ typedef struct xbt_swag_hookup { void *prev; } s_xbt_swag_hookup_t; /**< This type should be added to a type that is to be used in a swag. - * For example like that : + * + * Whenever a new object with this struct is created, all fields have + * to be set to NULL + * + * Here is an example like that : \code typedef struct foo { @@ -78,9 +90,15 @@ typedef struct xbt_swag { /**< A typical swag */ /* @} */ -/** \name Functions +/** @defgroup XBT_swag_func SWAG functions + * @ingroup XBT_swag + +
Top [\ref index]::[\ref XBT_API]::[\ref XBT_swag] +
Prev [\ref XBT_swag_type] +
Next [\ref XBT_swag_curs]
+ + * @{ */ -/* @{ */ xbt_swag_t xbt_swag_new(size_t offset); void xbt_swag_free(xbt_swag_t swag); @@ -106,6 +124,7 @@ static _XBT_INLINE void *xbt_swag_getFirst(xbt_swag_t swag) * \arg var a variable of type struct something * \arg field a field of struct something * \return the offset of \a field in struct something. + * @hideinitializer * * It is very similar to offsetof except that is done at runtime and that * you have to declare a variable. Why defining such a macro then ? @@ -115,8 +134,13 @@ static _XBT_INLINE void *xbt_swag_getFirst(xbt_swag_t swag) /* @} */ /** - * \name Swag iterator - * + * \defgroup XBT_swag_curs Swag cursor + * @ingroup XBT_swag + +
Top [\ref index]::[\ref XBT_API]::[\ref XBT_swag] +
Prev [\ref XBT_swag_func] +
Next
+ * Iterates over the whole swag. * * @{ */ @@ -151,6 +175,5 @@ static _XBT_INLINE void *xbt_swag_getFirst(xbt_swag_t swag) ((obj)?(obj_next=xbt_swag_getNext((obj),(swag)->offset)): \ (obj_next=NULL)) ) /* @} */ -/* @} */ #endif /* _XBT_SWAG_H */ diff --git a/include/xbt/sysdep.h b/include/xbt/sysdep.h index 2c7c194f52..7d41431806 100644 --- a/include/xbt/sysdep.h +++ b/include/xbt/sysdep.h @@ -22,11 +22,16 @@ SG_BEGIN_DECL() /** @addtogroup XBT_syscall + * @brief Malloc and associated functions, killing the program on error (with \ref XBT_ex) + * + *
Top [\ref index]::[\ref XBT_API] + *
Prev + *
Next [\ref XBT_ex]
* @{ */ -#ifdef __GNUC__ -/** @brief like strdup, but xbt_die() on error */ +#if defined(__GNUC__) || defined(DOXYGEN) +/** @brief Like strdup, but xbt_die() on error */ static inline char *xbt_strdup(const char *s) { char *res = NULL; if (s) { @@ -36,7 +41,7 @@ static inline char *xbt_strdup(const char *s) { } return res; } -/** @brief like malloc, but xbt_die() on error +/** @brief Like malloc, but xbt_die() on error @hideinitializer */ static inline void *xbt_malloc(int n){ void *res=malloc(n); -- 2.20.1