doxygen cleanups

git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@993 48e7efb5-ca39-0410-a469-dd3cf9ba447f

diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h
index 532dfdd..d4eb0e5 100644 (file)
--- 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:
  * 
  * \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:
  *
  * 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 
  * 
  *  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);
 
 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.
  * 
  * 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 ****
  ******************************************/
 
  **** Declare datadescription yourself ****
  ******************************************/
 

-/** \brief Declare a new structure description */

 gras_datadesc_type_t gras_datadesc_struct(const char *name);
 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_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_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_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);
 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);
 
 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.
  * 
  * 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.
  * 
  * 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 1a02519..f5be19d 100644 (file)
--- 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 
  *  
  *  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 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.
  * 
  * 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);

 
 /*@}*/
 
 
 /*@}*/