X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/a88936907b1c292cc7f1a966cdc958446d9a54ed..1d788f0aa070c370acfaa33dee4004958c48c145:/src/modules.doc

diff --git a/src/modules.doc b/src/modules.doc
index 69678ba6ac..30ad7c537a 100644
--- a/src/modules.doc
+++ b/src/modules.doc
@@ -62,6 +62,8 @@
       MSG was the first distributed programming environment provided within
       SimGrid. While almost realistic, it remains quite simple (simplistic?).
 
+      \section MSG_who Who should use this (and who shouldn't)
+      
       You should use this model if you want to study some heuristics for a
       given problem you don't really want to implement. If you want to get a
       real implementation of your solution, have a look at the \ref GRAS_API 
@@ -104,6 +106,8 @@
     encompassing both developer helping tools (the simulator and associated
     tools) and an efficient while portable execution runtime.
   
+    \section GRAS_who Who should use this (and who shouldn't)
+    
     You should use this programming environment if you want to develop real
     applications, ie if the final result of your work is a program which 
     may eventually be distributed. 
@@ -116,42 +120,52 @@
     consider implementing your own directly on top of \ref SURF_API (but you
     probably want to contact us before).
   
-    The user visibile features tend to offer several kind of functionnalities:
+    \section GRAS_funct Offered functionnalities
      - <b>Communication facilities</b>: Exchanging messages between peers
+       - \ref GRAS_dd: any data which may transit on the network must be
+         described beforehand so that GRAS can handle the platform
+         heterogeneity and convert them if needed.
+       - \ref GRAS_sock: this is how to open a communication channel to
+         other processes, and retrive information about them.
+       - \ref GRAS_msg: communications are message oriented. You have to
+         describe all possible messages and their payload beforehand, and
+         can then attach callbacks to the arrival of a given kind of message. 
      - <b>Virtualization</b>: Running both on top of the simulator and on
        top of real platforms, and portability support.
-*/     
-/**    \addtogroup GRAS_implem
-       \ingroup GRAS_API
-       
-       Internals of GRAS (forget it) */
-/**    \addtogroup GRAS_dd
-       \ingroup GRAS_API */
-/**    \addtogroup GRAS_dd_implem 
-       \ingroup GRAS_implem */
-/**    \defgroup GRAS_sock   Sockets
-       \ingroup GRAS_API
-       \brief Open/close sockets, and get info on peer (Communication facility). */
-/**    \defgroup GRAS_msg    Messages
-       \ingroup GRAS_API
-       \brief Defining messages and callbacks, and sending/receiving messages (Communication facility).
-                                 */
-/**    \defgroup GRAS_globals Globals
-       \ingroup GRAS_API
-       \brief Handling global variables so that it works on simulator (Virtualization).
+       - \ref GRAS_globals: The use of globals is forbidden since the
+         "processes" are threads in simulation mode. \n
+	 This is how to let GRAS handle your globals properly.
+       - \ref GRAS_cond: How to declare specific code for the simulation mode
+          or for the real mode.
+       - \ref GRAS_virtu: You naturally don't want to call the
+          gettimeofday(2) function in simulation mode since it would give
+          you the time on the host running the simulation, not the time in
+          the simulated world (you are belonging to).\n
+	  This a system call virtualization layer, which also acts as a
+          portability layer.
+	  
+    \section GRAS_todo TODO
+     Documentation related:
+       - Add an example to the \ref GRAS_msg section, at least
+       - Document examples/gras/gras_stub_generator utility and how to deal
+         with the fact that programs must have a main in RL and not in SG.
+       - Document example/gras/ping as it uses almost all of the GRAS
+         features.
+     
+     Code related: too long to be written here. See the TODO file
      
-       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
-       let GRAS handle it.
-       
-       Use the \ref gras_userdata_new macro to create a new user data (or malloc it
-       and use \ref gras_userdata_set yourself), and \ref gras_userdata_get to
-       retrive a reference to it. */
+    @{
+*/     
+
+       /** \defgroup GRAS_dd      Data description      */       
+       /** \defgroup GRAS_sock    Sockets               */           
+       /** \defgroup GRAS_msg     Messages              */               
+	 
+       /** \defgroup GRAS_globals Globals               */ 
+       /** \defgroup GRAS_cond    Conditional execution */ 
+       /** \defgroup GRAS_virtu   Syscalls              */ 
 
-/**    \defgroup GRAS_virtu Syscalls
-       \ingroup GRAS_API
-       \brief System call abstraction layer (Virtualization). */
+/** @} */ 
 
 /** \defgroup SMPI_API      SMPI
     \ingroup SimGrid_API
@@ -162,6 +176,8 @@
     for that. In other words, it will constitute an emulation solution for
     parallel codes.
     
+    \section SMPI_who Who should use this (and who shouldn't)
+    
     You should use this programming environment of the SimGrid suite if you
     want to study existing MPI applications.
     If you want to work on a distributed application, have a look at the