From d88979392aa995371340597cbfc45f1cd33fe643 Mon Sep 17 00:00:00 2001 From: mquinson Date: Sun, 13 Feb 2005 16:08:12 +0000 Subject: [PATCH] doxygen cleanups git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@993 48e7efb5-ca39-0410-a469-dd3cf9ba447f --- include/gras/datadesc.h | 72 ++++++++++++-------------------- include/gras/messages.h | 92 ++++++++++++++++++----------------------- 2 files changed, 68 insertions(+), 96 deletions(-) diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h index 532dfdd43b..d4eb0e551a 100644 --- a/include/gras/datadesc.h +++ b/include/gras/datadesc.h @@ -27,15 +27,15 @@ BEGIN_DECL() * * \warning At least, I would like to present those sections in the right order, but doxygen prevents me * from doing so. There is a weird bug I fail to circumvent here. The right order is naturally: - * - a) basic operations - * - b) Automatic parsing - * - c) Simple manual definitions - * - d) Callback Persistant State: Simple push/pop mecanism - * - e) Callback Persistant State: Full featured mecanism + * -# basic operations + * -# Automatic parsing + * -# Simple manual definitions + * -# Callback Persistant State: Simple push/pop mecanism + * -# Callback Persistant State: Full featured mecanism */ /*@{*/ -/** @name a) basic operations +/** @name 1. basic operations * * If you only want to send pre-existing types, simply retrieve the pre-defined description with * the \ref gras_datadesc_by_name function. Existing types entail: @@ -58,7 +58,7 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); /* @} */ -/** @name b) Automatic parsing +/** @name 2. Automatic parsing * * If you need to declare a new datatype, this is the simplest way to describe it to GRAS. Simply * enclose its type definition into a \ref GRAS_DEFINE_TYPE macro call, and you're set. Here is @@ -130,7 +130,7 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name); gras_datadesc_type_t gras_datadesc_parse(const char *name, const char *C_statement); -/** @name c) Simple manual definitions +/** @name 3. Simple manual definitions * * Here are the functions to use if you want to declare your description manually. * The function names should be self-explanatory in most cases. @@ -183,54 +183,36 @@ typedef gras_datadesc_type_t (*gras_datadesc_selector_t)(gras_cbps_t vars, void **** Declare datadescription yourself **** ******************************************/ -/** \brief Declare a new structure description */ gras_datadesc_type_t gras_datadesc_struct(const char *name); +void gras_datadesc_struct_append(gras_datadesc_type_t struct_type, + const char *name, + gras_datadesc_type_t field_type); +void gras_datadesc_struct_close(gras_datadesc_type_t struct_type); -/** \brief Append a new field to a structure description */ -void - gras_datadesc_struct_append(gras_datadesc_type_t struct_type, - const char *name, - gras_datadesc_type_t field_type); -/** \brief Close a structure description */ -void - gras_datadesc_struct_close(gras_datadesc_type_t struct_type); -/** \brief Declare a new union description */ -gras_datadesc_type_t - gras_datadesc_union(const char *name, - gras_datadesc_type_cb_int_t selector); -/** \brief Append a new field to an union description */ -void - gras_datadesc_union_append(gras_datadesc_type_t union_type, - const char *name, - gras_datadesc_type_t field_type); -/** \brief Close an union description */ -void - gras_datadesc_union_close(gras_datadesc_type_t union_type); +gras_datadesc_type_t gras_datadesc_union(const char *name, + gras_datadesc_type_cb_int_t selector); +void gras_datadesc_union_append(gras_datadesc_type_t union_type, + const char *name, + gras_datadesc_type_t field_type); +void gras_datadesc_union_close(gras_datadesc_type_t union_type); -/** \brief Declare a new type being a reference to the one passed in arg */ gras_datadesc_type_t - gras_datadesc_ref(const char *name, - gras_datadesc_type_t referenced_type); -/** \brief Declare a new type being a generic reference. */ + gras_datadesc_ref(const char *name, + gras_datadesc_type_t referenced_type); gras_datadesc_type_t - gras_datadesc_ref_generic(const char *name, - gras_datadesc_selector_t selector); + gras_datadesc_ref_generic(const char *name, + gras_datadesc_selector_t selector); -/** \brief Declare a new type being an array of fixed size and content */ gras_datadesc_type_t - gras_datadesc_array_fixed(const char *name, - gras_datadesc_type_t element_type, - long int fixed_size); - -/** \brief Declare a new type being an array of fixed size, but accepting several content types. */ + gras_datadesc_array_fixed(const char *name, + gras_datadesc_type_t element_type, + long int fixed_size); gras_datadesc_type_t gras_datadesc_array_dyn(const char *name, gras_datadesc_type_t element_type, gras_datadesc_type_cb_int_t dynamic_size); - -/** \brief Declare a new type being an array which size can be found with \ref gras_cbps_i_pop */ gras_datadesc_type_t gras_datadesc_ref_pop_arr(gras_datadesc_type_t element_type); @@ -270,7 +252,7 @@ int gras_datadesc_get_id(gras_datadesc_type_t ddt); /*@}*/ -/** @name d) Callback Persistant State: Simple push/pop mecanism +/** @name 4. Callback Persistant State: Simple push/pop mecanism * * Sometimes, one of the callbacks need to leave information for the next ones. If this is a simple integer (such as * an array size), you can use the functions described here. If not, you'll have to play with the complete cbps interface. @@ -307,7 +289,7 @@ void gras_datadesc_cb_push_ulint(gras_cbps_t vars, void *data); /*@}*/ -/** @name e) Callback Persistant State: Full featured mecanism +/** @name 5. Callback Persistant State: Full featured mecanism * * Sometimes, one of the callbacks need to leave information for the next ones. If the simple push/pop mecanism * introduced in previous section isn't enough, you can always use this full featured one. diff --git a/include/gras/messages.h b/include/gras/messages.h index 1a025195c0..f5be19d861 100644 --- a/include/gras/messages.h +++ b/include/gras/messages.h @@ -37,7 +37,7 @@ BEGIN_DECL() * @{ */ -/** @name Message declaration and retrival +/** @name 1. Message declaration and retrival * * GRAS messages can only accept one type of payload. If you absolutely want to declare a message * able to convey several datatypes, you can always say that it conveys a generic reference (see @@ -54,22 +54,17 @@ BEGIN_DECL() /** \brief Opaque type */ typedef struct s_gras_msgtype *gras_msgtype_t; -/** \brief declare a new message type of the given name. It only accepts the given datadesc as payload */ -void gras_msgtype_declare (const char *name, - gras_datadesc_type_t payload); -/** \brief declare a new versionned message type of the given name and payload. */ -void gras_msgtype_declare_v(const char *name, - short int version, - gras_datadesc_type_t payload); - -/** \brief retrive an existing message type from its name. */ -gras_msgtype_t gras_msgtype_by_name (const char *name); -/** \brief retrive an existing message type from its name and version number. */ -gras_msgtype_t gras_msgtype_by_namev(const char *name, - short int version); -/** @} */ + void gras_msgtype_declare (const char *name, + gras_datadesc_type_t payload); + void gras_msgtype_declare_v(const char *name, + short int version, + gras_datadesc_type_t payload); + + gras_msgtype_t gras_msgtype_by_name (const char *name); + gras_msgtype_t gras_msgtype_by_namev(const char *name, short int version); -/** @name Callback declaration and use +/** @} */ +/** @name 2. Callback declaration and use * * This is how to register a given function so that it gets called when a * given type of message arrives. @@ -83,44 +78,39 @@ gras_msgtype_t gras_msgtype_by_namev(const char *name, * @{ */ -/** \brief Type of message callback functions. - * \param msg: The message itself - * \return true if the message was consumed by the callback, false if the message was - * refused by the callback (and should be passed to the next callback of the stack for - * this message) - * - * Once a such a function is registered to handle messages of a given type with - * \ref gras_cb_register(), it will be called each time such a message arrives. - * - * If the callback accepts the message, it should free it after use. - */ -typedef int (*gras_cb_t)(gras_socket_t expeditor, - void *payload); -/** \brief Bind the given callback to the given message type - * - * Several callbacks can be attached to a given message type. The lastly added one will get the message first, and - * if it returns false, the message will be passed to the second one. - * And so on until one of the callbacks accepts the message. - */ -void gras_cb_register (gras_msgtype_t msgtype, - gras_cb_t cb); -/** \brief Unbind the given callback from the given message type */ -void gras_cb_unregister(gras_msgtype_t msgtype, - gras_cb_t cb); + /** \brief Type of message callback functions. + * + * \param expeditor: a socket to contact who sent this message + * \param payload: the message itself + * + * \return true if the message was consumed by the callback, + * false if the message was refused by the callback (and should be + * passed to the next callback of the stack for this message) + * + * Once a such a function is registered to handle messages of a given + * type with \ref gras_cb_register(), it will be called each time such + * a message arrives (unless a gras_msg_wait() intercepts it on arrival). + * + * If the callback accepts the message, it should free it after use. + */ + typedef int (*gras_msg_cb_t)(gras_socket_t expeditor, + void *payload); + + void gras_cb_register (gras_msgtype_t msgtype, gras_msg_cb_t cb); + void gras_cb_unregister(gras_msgtype_t msgtype, gras_msg_cb_t cb); /** @} */ -/** @name Message exchange */ +/** @name 3. Message exchange */ /** @{ */ -/** \brief Send the data pointed by \a payload as a message of type \a msgtype to the peer \a sock */ -xbt_error_t gras_msg_send(gras_socket_t sock, - gras_msgtype_t msgtype, - void *payload); -/** \brief Waits for a message to come in over a given socket. */ -xbt_error_t gras_msg_wait(double timeout, - gras_msgtype_t msgt_want, - gras_socket_t *expeditor, - void *payload); -xbt_error_t gras_msg_handle(double timeOut); + + xbt_error_t gras_msg_send(gras_socket_t sock, + gras_msgtype_t msgtype, + void *payload); + xbt_error_t gras_msg_wait(double timeout, + gras_msgtype_t msgt_want, + gras_socket_t *expeditor, + void *payload); + xbt_error_t gras_msg_handle(double timeOut); /*@}*/ -- 2.20.1