Documentation reorganization: no @name anymore since doxygen was buggy on it until...

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

diff --git a/include/gras/datadesc.h b/include/gras/datadesc.h
index e259f44..3df17d1 100644 (file)
--- a/include/gras/datadesc.h
+++ b/include/gras/datadesc.h
@@ -18,25 +18,35 @@ SG_BEGIN_DECL()
 /** @addtogroup GRAS_dd Data description
  *  @brief Describing data to be exchanged (Communication facility)
  *
 /** @addtogroup GRAS_dd Data description
  *  @brief Describing data to be exchanged (Communication facility)
  *

- * @section Overview
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
+ *                <tr><td>Prev          <td> 
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_sock]
+ *                <tr><td><b>Down</b>   <td> [\ref GRAS_dd_basic]            </table></center>

  *
  * Since GRAS takes care of potential representation conversion when the platform is heterogeneous, 
  * any data which transits on the network must be described beforehand.
  * 
  * There is several possible interfaces for this, ranging from the really completely automatic parsing to 
  *
  * Since GRAS takes care of potential representation conversion when the platform is heterogeneous, 
  * any data which transits on the network must be described beforehand.
  * 
  * There is several possible interfaces for this, ranging from the really completely automatic parsing to 

- * completely manual. Let's study each of them from the simplest to the more advanced.
+ * completely manual. Let's study each of them from the simplest to the more advanced:

  * 
  * 

- * \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:
- *   -# basic operations
- *   -# Automatic parsing
- *   -# Simple manual definitions
- *   -# Callback Persistant State: Simple push/pop mechanism
- *   -# Callback Persistant State: Full featured mechanism
- */
-/* @{*/
-
-/** @name 1. basic operations
+ *   - Section \ref GRAS_dd_basic presents how to retrieve and use an already described type.
+ *   - Section \ref GRAS_dd_auto shows how to get GRAS parsing your type description automagically. This
+ *     is unfortunately not always possible (only works for some structures), but if it is for your data,
+ *     this is definitly the way to go.
+ *   - Section \ref GRAS_dd_manual presents how to build a description manually. This is useful when you want
+ *     to describe an array or a pointer of pre-defined structures.
+ *   - You sometimes need to exchange informations between descriptions at send or receive time. This is 
+ *     for example useful when your structure contains an array which size is given by another field of the 
+ *     structure.
+ *     - Section \ref GRAS_dd_cb_simple provides a simple interface to do so, allowing to share integers stored on a stack.
+ *     - Section \ref GRAS_dd_cb_full provides a full featured interface to do so, but it may reveal somehow difficult to use.
+ **/
+
+/** @defgroup GRAS_dd_basic Basic operations on data descriptions
+ *  @ingroup GRAS_dd
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ *                <tr><td>   Prev       <td> 
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_dd_auto]            </table></center>

  *
  * 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:


@@ -48,6 +58,7 @@ SG_BEGIN_DECL()
  * Example:\verbatim gras_datadesc_type_t i = gras_datadesc_by_name("int");
  gras_datadesc_type_t uc = gras_datadesc_by_name("unsigned char");
  gras_datadesc_type_t str = gras_datadesc_by_name("string");\endverbatim
  * Example:\verbatim gras_datadesc_type_t i = gras_datadesc_by_name("int");
  gras_datadesc_type_t uc = gras_datadesc_by_name("unsigned char");
  gras_datadesc_type_t str = gras_datadesc_by_name("string");\endverbatim

+ *

  */
 /* @{ */
   
  */
 /* @{ */
   


@@ -59,7 +70,11 @@ gras_datadesc_type_t gras_datadesc_by_name(const char *name);
 
 /* @} */
     
 
 /* @} */
     

-/** @name 2. Automatic parsing
+/** @defgroup GRAS_dd_auto Automatic parsing of data descriptions
+ *  @ingroup GRAS_dd
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_dd_basic]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_dd_manual]            </table></center>

  * 
  *  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 


@@ -148,7 +163,11 @@ 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 3. Simple manual definitions
+/** @defgroup GRAS_dd_manual Simple manual data description
+ *  @ingroup GRAS_dd
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_dd_auto]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_dd_cb_simple]            </table></center>

  * 
  * 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.


@@ -277,7 +296,11 @@ int gras_datadesc_get_id(gras_datadesc_type_t ddt);
 
 /* @} */
 
 
 /* @} */
 

-/** @name 4. Callback Persistant State: Simple push/pop mechanism
+/** @defgroup GRAS_dd_cb_simple Data description with Callback Persistant State: Simple push/pop mechanism
+ *  @ingroup GRAS_dd
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_dd_manual]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_dd_cb_full]            </table></center>

  * 
  * 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.


@@ -342,7 +365,11 @@ void gras_datadesc_cb_push_ulint_mult(gras_datadesc_type_t typedesc, gras_cbps_t
 
 /* @} */
 
 
 /* @} */
 

-/** @name 5. Callback Persistant State: Full featured mechanism
+/** @defgroup GRAS_dd_cb_full Data description with Callback Persistant State: Full featured interface
+ *  @ingroup GRAS_dd
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_dd]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_dd_cb_simple]
+ *                <tr><td>Next          <td>             </table></center>

  * 
  * Sometimes, one of the callbacks need to leave information for the next ones. If the simple push/pop mechanism
  * 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 mechanism
  * introduced in previous section isn't enough, you can always use this full featured one.

diff --git a/include/gras/emul.h b/include/gras/emul.h
index a183509..addace8 100644 (file)
--- a/include/gras/emul.h
+++ b/include/gras/emul.h
@@ -18,6 +18,10 @@ SG_BEGIN_DECL()
 /** @addtogroup GRAS_emul
  *  @brief Code execution "emulation" and "virtualization".
  * 
 /** @addtogroup GRAS_emul
  *  @brief Code execution "emulation" and "virtualization".
  * 

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_globals]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_main_generation]            </table></center>
+ *

  *  Emulation and virtualization words have a lot of different meanings in
  *  computer science. Here is what we mean, and what this module allows you
  *  to do (if it does not match your personal belives, I'm sorry):
  *  Emulation and virtualization words have a lot of different meanings in
  *  computer science. Here is what we mean, and what this module allows you
  *  to do (if it does not match your personal belives, I'm sorry):

diff --git a/include/gras/messages.h b/include/gras/messages.h
index d704834..dee7f8b 100644 (file)
--- a/include/gras/messages.h
+++ b/include/gras/messages.h
@@ -20,6 +20,11 @@ SG_BEGIN_DECL()
 /** @addtogroup GRAS_msg
  *  @brief Defining messages and callbacks, and exchanging messages (Communication facility) 
  * 
 /** @addtogroup GRAS_msg
  *  @brief Defining messages and callbacks, and exchanging messages (Communication facility) 
  * 

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_sock]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_timer]
+ *                <tr><td><b>Down</b>   <td> [\ref GRAS_msg_decl]            </table></center>
+ *

  *  There is two way to receive messages in GRAS. The first one is to
  *  register a given function as callback to a given type of messages (see
  *  \ref gras_cb_register and associated section). But you can also
  *  There is two way to receive messages in GRAS. The first one is to
  *  register a given function as callback to a given type of messages (see
  *  \ref gras_cb_register and associated section). But you can also


@@ -37,8 +42,12 @@ SG_BEGIN_DECL()
  *  @{
  */
 
  *  @{
  */
 

-/** @name 1. Message declaration and retrival 
+/** @defgroup GRAS_msg_decl Message declaration and retrival 

  *  
  *  

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ *                <tr><td>   Prev       <td> 
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_msg_cb]               </table></center>
+ *

  *  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 
  *  \ref gras_datadesc_ref_generic).
  *  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 
  *  \ref gras_datadesc_ref_generic).


@@ -65,8 +74,12 @@ typedef struct s_gras_msgtype *gras_msgtype_t;
   gras_msgtype_t gras_msgtype_by_id(int id);
 
 /** @} */  
   gras_msgtype_t gras_msgtype_by_id(int id);
 
 /** @} */  

-/** @name 2. Callback declaration and use
+/** @defgroup GRAS_msg_cb Callback declaration and use

  * 
  * 

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_msg_decl]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_msg_exchange]       </table></center>
+ *

  * 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.
  * 


@@ -101,7 +114,12 @@ typedef struct s_gras_msgtype *gras_msgtype_t;
   void gras_cb_unregister(gras_msgtype_t msgtype, gras_msg_cb_t cb);
 
 /** @} */  
   void gras_cb_unregister(gras_msgtype_t msgtype, gras_msg_cb_t cb);
 
 /** @} */  

-/** @name 3. Message exchange */
+/** @defgroup GRAS_msg_exchange Message exchange 
+ *
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_msg]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_msg_cb]
+ *                <tr><td>   Next       <td>                        </table></center>
+ */

 /** @{ */
 
   void gras_msg_send(gras_socket_t   sock,
 /** @{ */
 
   void gras_msg_send(gras_socket_t   sock,


@@ -114,6 +132,7 @@ typedef struct s_gras_msgtype *gras_msgtype_t;
   void gras_msg_handle(double timeOut);
 
 /* @} */
   void gras_msg_handle(double timeOut);
 
 /* @} */

+/* @} */

 
 SG_END_DECL()
 
 
 SG_END_DECL()
 

diff --git a/include/gras/process.h b/include/gras/process.h
index 15dd07f..57f8b4c 100644 (file)
--- a/include/gras/process.h
+++ b/include/gras/process.h
@@ -38,6 +38,10 @@ void gras_process_exit(void);
 /** \addtogroup GRAS_globals
  *  \brief Handling global variables so that it works on simulator (Virtualization).
  * 
 /** \addtogroup GRAS_globals
  *  \brief Handling global variables so that it works on simulator (Virtualization).
  * 

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_virtu]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_emul]            </table></center>
+ *

  * In GRAS, using globals is forbidden since the "processes" will
  * sometimes run as a thread inside the same process (namely, in
  * simulation mode). So, you have to put all globals in a structure, and
  * In GRAS, using globals is forbidden since the "processes" will
  * sometimes run as a thread inside the same process (namely, in
  * simulation mode). So, you have to put all globals in a structure, and

diff --git a/include/gras/timer.h b/include/gras/timer.h
index f12c599..00afd4d 100644 (file)
--- a/include/gras/timer.h
+++ b/include/gras/timer.h
@@ -18,6 +18,10 @@ SG_BEGIN_DECL()
 /** @addtogroup GRAS_timer
  *  @brief Delayed and repetitive tasks (Communication facility)
  *
 /** @addtogroup GRAS_timer
  *  @brief Delayed and repetitive tasks (Communication facility)
  *

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_msg]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_virtu]            </table></center>
+ *

  *  This is how to have a specific function called only once after the
  *  specified amount of time or a function executed every 5 mn until it gets 
  *  removed. In the UNIX world, this is comparable to <tt>at</tt> and 
  *  This is how to have a specific function called only once after the
  *  specified amount of time or a function executed every 5 mn until it gets 
  *  removed. In the UNIX world, this is comparable to <tt>at</tt> and 

diff --git a/include/gras/transport.h b/include/gras/transport.h
index 1e7ceac..2d8961e 100644 (file)
--- a/include/gras/transport.h
+++ b/include/gras/transport.h
@@ -13,10 +13,26 @@
 
 /** \addtogroup GRAS_sock
  *  \brief Socket handling (Communication facility).
 
 /** \addtogroup GRAS_sock
  *  \brief Socket handling (Communication facility).

+ *
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_dd] 
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_msg]
+ *                <tr><td><b>Down</b>   <td> [\ref GRAS_sock_create]          </table></center>
+ *
+ * The model of communications in GRAS is very close to the BSD socket one. To get two hosts 
+ * exchanging data, one of them need to open a <i>server</i> socket on which it can listen for incoming messages
+ * and the other one must connect a <i>client</i> socket onto the server one.
+ * 
+ * If you need an example of this, check \ref GRAS_ex_ping.
+ *

  */
  */

-
-/** \name Socket creation functions
+ 
+/** \defgroup GRAS_sock_create Socket creation functions

  *  \ingroup GRAS_sock
  *  \ingroup GRAS_sock

+ *
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
+ *                <tr><td>Prev          <td> 
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_sock_info]            </table></center>

  */
 /* @{*/
 /** \brief Opaque type describing a socket */
  */
 /* @{*/
 /** \brief Opaque type describing a socket */


@@ -39,9 +55,13 @@ gras_socket_t gras_socket_server_ext(unsigned short port,
                                     unsigned long int bufSize,
                                     int measurement);
 /* @}*/
                                     unsigned long int bufSize,
                                     int measurement);
 /* @}*/

-/** \name Retrieving data about sockets and peers 
+/** \defgroup GRAS_sock_info Retrieving data about sockets and peers 

  *  \ingroup GRAS_sock
  * 
  *  \ingroup GRAS_sock
  * 

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_sock_create]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_sock_meas]         </table></center>
+ *

  * Who are you talking to?
  */
 /* @{*/
  * Who are you talking to?
  */
 /* @{*/


@@ -54,9 +74,13 @@ int   gras_socket_peer_port(gras_socket_t sock);
 char *gras_socket_peer_name(gras_socket_t sock);
 /* @}*/
 
 char *gras_socket_peer_name(gras_socket_t sock);
 /* @}*/
 

-/** \name Using measurement sockets
+/** \defgroup GRAS_sock_meas Using measurement sockets

  *  \ingroup GRAS_sock
  * 
  *  \ingroup GRAS_sock
  * 

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_sock_info]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_sock_file]         </table></center>
+ *

  * You may want to use sockets not to exchange valuable data (in messages), 
  * but to conduct some bandwidth measurements and related experiments. If so, try those measurement sockets.
  * 
  * You may want to use sockets not to exchange valuable data (in messages), 
  * but to conduct some bandwidth measurements and related experiments. If so, try those measurement sockets.
  * 


@@ -80,9 +104,13 @@ gras_socket_t gras_socket_meas_accept(gras_socket_t peer);
             
 /* @}*/
 
             
 /* @}*/
 

-/** \name Using files as sockets
+/** \defgroup GRAS_sock_file Using files as sockets

  *  \ingroup GRAS_sock
  * 
  *  \ingroup GRAS_sock
  * 

+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]::[\ref GRAS_sock]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_sock_meas]
+ *                <tr><td>Next          <td>          </table></center>
+ *

  * For debugging purpose, it is possible to deal with files as if they were sockets.
  * It can even be useful to store stuff in a portable manner, but writing messages to a file
  * may be strange...
  * For debugging purpose, it is possible to deal with files as if they were sockets.
  * It can even be useful to store stuff in a portable manner, but writing messages to a file
  * may be strange...

diff --git a/include/gras/virtu.h b/include/gras/virtu.h
index 2eb87e5..1314148 100644 (file)
--- a/include/gras/virtu.h
+++ b/include/gras/virtu.h
@@ -16,6 +16,11 @@ SG_BEGIN_DECL()
 
 /** @addtogroup GRAS_virtu  
  *  @brief System call abstraction layer (Virtualization).
 
 /** @addtogroup GRAS_virtu  
  *  @brief System call abstraction layer (Virtualization).

+ *
+ * <center><table><tr><td><b>Top</b>    <td> [\ref index]::[\ref GRAS_API]
+ *                <tr><td><b>Prev</b>   <td> [\ref GRAS_timer]
+ *                <tr><td><b>Next</b>   <td> [\ref GRAS_globals]            </table></center>
+ *

  *  @{
  */
 
  *  @{
  */