From: Martin Quinson <martin.quinson@loria.fr>
Date: Wed, 21 Mar 2012 20:31:48 +0000 (+0100)
Subject: further improve the MSG doc by documenting the examples
X-Git-Tag: v3_7~274
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/0821eaf865ee5431f938481ede3c2e77ef095f65

further improve the MSG doc by documenting the examples
---

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 912a833c2a..a23b712752 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -657,7 +657,7 @@ INPUT                  = index.doc \
                          @top_srcdir@/include/gras \
                          @top_srcdir@/include/amok \
                          @top_srcdir@/include/xbt \
-                         @top_srcdir@/include/simdag \
+                         @top_srcdir@/include/simdag \			 
                          @top_srcdir@/src/include/surf \
                          @top_srcdir@/src/xbt/ \
                          @top_srcdir@/src/xbt/datadesc \
@@ -672,6 +672,36 @@ INPUT                  = index.doc \
                          @top_srcdir@/src/amok/PeerManagement \
                          @top_srcdir@/src/simdag
 
+###################################################
+##  PLEASE DON'T MESS WITH THE ORDER OF EXAMPLES ## (unless you know what you are doing, of course)
+###################################################
+
+INPUT +=                 @top_srcdir@/examples/msg/sendrecv/sendrecv.c \
+                         @top_srcdir@/examples/msg/masterslave/masterslave_forwarder.c \
+                         @top_srcdir@/examples/msg/masterslave/masterslave_console.c \
+                         @top_srcdir@/examples/msg/migration \
+                         @top_srcdir@/examples/msg/suspend \
+                         @top_srcdir@/examples/msg/properties \
+                         @top_srcdir@/examples/msg/parallel_task \
+                         @top_srcdir@/examples/msg/priority \
+                         @top_srcdir@/examples/msg/icomms/peer.c \
+                         @top_srcdir@/examples/msg/icomms/peer2.c \
+                         @top_srcdir@/examples/msg/icomms/peer3.c \
+			 @top_srcdir@/examples/msg/tracing/simple.c \
+			 @top_srcdir@/examples/msg/tracing/ms.c \
+			 @top_srcdir@/examples/msg/tracing/categories.c \
+			 @top_srcdir@/examples/msg/tracing/procmig.c \
+			 @top_srcdir@/examples/msg/tracing/trace_platform.c \
+			 @top_srcdir@/examples/msg/tracing/user_variables.c \
+			 @top_srcdir@/examples/msg/ns3 \
+			 @top_srcdir@/examples/msg/gtnets \
+			 @top_srcdir@/examples/msg/io \
+			 @top_srcdir@/examples/msg/gpu \
+                         @top_srcdir@/examples/msg/actions \
+                         @top_srcdir@/examples/msg/token_ring \
+                         @top_srcdir@/examples/msg/pmm \
+                         @top_srcdir@/examples/msg/chord \
+
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
 # also the default input encoding. Doxygen uses libiconv (or the iconv built
diff --git a/doc/module-msg.doc b/doc/module-msg.doc
index e5c554933b..77a857ce54 100644
--- a/doc/module-msg.doc
+++ b/doc/module-msg.doc
@@ -21,11 +21,7 @@
    - \ref msg_easier_life
    - \ref msg_simulation
 
-  \section MSG_examples Examples of MSG
- 
-   - \ref MSG_ex_master_slave
-   - \ref MSG_ex_asynchronous_communications
-   - \ref MSG_ex_master_slave_scrip_lua
+  Also make sure to visit the page @ref MSG_examples.
 */
 
 
@@ -75,7 +71,19 @@
 
 @htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation functions" --> @endhtmlonly
 */
+
+
+/**
+@defgroup MSG_examples MSG Examples
+@ingroup MSG_API
  
+MSG comes with an extensive set of examples. It is sometimes difficult
+to find the one you need. 
+
+@section MSG_ex_basics Basic examples and features
+
+*/
+
 /**
 @defgroup MSG_LUA      Lua bindings
 @ingroup MSG_API
@@ -109,12 +117,13 @@
  
    - \ref MSG_ex_master_slave_lua
    - \ref MSG_ex_master_slave_lua_bypass
-   - Also, the Chord example (in the source tree) is a working
-     non-trivial example of use of the lua bindings
+   - Also, the lua version of the Chord example (in the source tree)
+     is a working non-trivial example of use of the lua bindings
 */
 
 
-/** \page MSG_ex_asynchronous_communications Asynchronous communication applications
+/** \defgroup MSG_ex_asynchronous_communications Asynchronous communications
+    \ingroup MSG_examples
 
     Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
     an external description of the deployment.
@@ -221,89 +230,8 @@
 
 */
 
-/** \page MSG_ex_master_slave_scrip_lua Master/slave application using lua console
-	    
-    Simulation of a master-slave application using a realistic platform and
-    an external description of the deployment via a lua script.
-
-    \section MSG_ex_msl_TOC Table of contents:
-	
-     - \ref MSG_ext_msl_code
-       - \ref MSG_ext_msl_preliminary
-       - \ref MSG_ext_msl_master
-       - \ref MSG_ext_msl_slave
-       - \ref MSG_ext_msl_core
-       - \ref MSG_ext_msl_main
-     - \ref MSG_ext_msl_helping
-       - \ref MSG_ext_msl_platform
-
-<hr> 
-    
-    \dontinclude msg/masterslave/masterslave_console.c
-    
-    \section MSG_ext_msl_code Code of the application
-    
-    \subsection MSG_ext_msl_preliminary Preliminary declarations
-    
-    \skip include
-    \until } channel_t;
-    
-    \subsection MSG_ext_msl_master Master code
-    
-      This function has to be assigned to a m_process_t that will behave as the master.
-      It should not be called directly but either given as a parameter to
-      #MSG_process_create() or registered as a public function through 
-      #MSG_function_register() and then automatically assigned to a process through
-      #MSG_load_platform_script(). 
- 
-      C style arguments (argc/argv) are interpreted as:
-       - the number of tasks to distribute
-       - the computation size of each task
-       - the size of the files associated to each task
-       - number of hosts that will accept those tasks.
-
-      Tasks are dumbly sent in a round-robin style.
-      
-      \until end_of_master
-\subsection MSG_ext_msl_slave Slave code
-    
-      This function has to be assigned to a #m_process_t that has to behave as a slave.
-      Just like the master fuction (described in \ref MSG_ext_ms_master), it should not be called directly.
-
-      This function keeps waiting for tasks and executes them as it receives them.
-      
-      \until end_of_slave
-
-\subsection MSG_ext_msl_core Simulation core
-
-      This function is the core of the simulation and is divided now only into 2 parts
-      thanks to MSG_load_platform_script().
-         -# Simulation settings and application deployment : MSG_load_platform_script() loads and creates a realistic 
-            environment and the agents on the right locations, described in the lua script file (see example below).
-	    Note that the use of this function require a lua installation on your machine. 
-         -# The simulation is run with #MSG_main().
-	 
-      Its arguments are:
-	- <i>platform_script_file</i>: the name of the script file containing a valid  platform and application description, using bound lua methods to bypass the surfxml parser.
-
-      \until end_of_test_all
-
-\subsection MSG_ext_msl_main Main() function
-   
-      This initializes MSG, runs a simulation, and free all data-structures created by MSG.
-      
-      \until end_of_main
-
-   \section MSG_ext_msl_helping Helping files
-
-   \subsection MSG_ext_msl_platform Example of platform script file
-
-   \include msg/masterslave/platform_script.lua
-
-
-*/
-
-/** \page MSG_ex_master_slave Master/slave application
+/** @defgroup MSG_ex_master_slave Basic Master/Slaves
+    @ingroup MSG_examples
     
     Simulation of a master-slave application using a realistic platform and
     an external description of the deployment. 
diff --git a/examples/msg/actions/actions.c b/examples/msg/actions/actions.c
index 2448f93fad..edaed915e6 100644
--- a/examples/msg/actions/actions.c
+++ b/examples/msg/actions/actions.c
@@ -11,6 +11,34 @@
 #include "xbt.h"                /* calloc, printf */
 #include "instr/instr_private.h"
 
+/** @addtogroup MSG_examples
+ *
+ *  @section MSG_ex_actions Trace driven simulations
+ * 
+ *  The <b>actions/actions.c</b> example demonstrates how to run trace-driven simulations. It
+ *  is very handy when you want to test an algorithm or protocol that
+ *  does nothing unless it receives some events from outside. For
+ *  example, a P2P protocol reacts to requests from the user, but
+ *  does nothing if there is no such event. 
+ * 
+ *  In such situations, SimGrid allows to write your protocol in your
+ *  C file, and the events to react to in a separate text file.
+ *  Declare a function handling each of the events that you want to
+ *  accept in your trace files, register them using @ref
+ *  MSG_action_register in your main, and then use @ref
+ *  MSG_action_trace_run to launch the simulation. You can either
+ *  have one trace file containing all your events, or a file per
+ *  simulated process. Check the tesh files in the example directory
+ *  for details on how to do it.
+ *
+ *  This example uses this approach to replay MPI-like traces. It
+ *  comes with a set of event handlers reproducing MPI events. This
+ *  is somehow similar to SMPI, yet differently implemented. This
+ *  code should probably be changed to use SMPI internals instead,
+ *  but wasn't, so far.
+ * 
+ */
+
 XBT_LOG_NEW_DEFAULT_CATEGORY(actions,
                              "Messages specific for this msg example");
 int communicator_size = 0;
diff --git a/examples/msg/chord/chord.c b/examples/msg/chord/chord.c
index 038c754acb..b11287434b 100644
--- a/examples/msg/chord/chord.c
+++ b/examples/msg/chord/chord.c
@@ -11,7 +11,17 @@
 #include "xbt/asserts.h"
 #include "simgrid/modelchecker.h"
 
-XBT_LOG_NEW_DEFAULT_CATEGORY(msg_chord,
+/** @addtogroup MSG_examples
+ *
+ *  - <b>chord/chord.c: Classical Chord P2P protocol</b>
+ *    This example implements the well known Chord P2P protocol. Its
+ *    main advantage is that it constitute a fully working non-trivial
+ *    example. In addition, its implementation is rather efficient, as 
+ *    demonstrated in http://hal.inria.fr/inria-00602216/
+ */
+
+ 
+ XBT_LOG_NEW_DEFAULT_CATEGORY(msg_chord,
                              "Messages specific for this msg example");
 
 #define COMM_SIZE 10
diff --git a/examples/msg/gpu/test_MSG_gpu_task_create.c b/examples/msg/gpu/test_MSG_gpu_task_create.c
index 05d34bfc88..883f035c04 100644
--- a/examples/msg/gpu/test_MSG_gpu_task_create.c
+++ b/examples/msg/gpu/test_MSG_gpu_task_create.c
@@ -4,6 +4,11 @@
 /* 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 MSG_examples
+ * 
+ * - <b>gpu/test_MSG_gpu_task_create.c</b> Example of use of the very experimental (for now) GPU resource. 
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include "msg/msg.h"
diff --git a/examples/msg/gtnets/gtnets.c b/examples/msg/gtnets/gtnets.c
index 11a895ef50..003672f0ff 100644
--- a/examples/msg/gtnets/gtnets.c
+++ b/examples/msg/gtnets/gtnets.c
@@ -13,6 +13,11 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ * - <b>gtnets</b> Simple ping-pong using GTNeTs instead of the SimGrid network models.
+ */
+
 int master(int argc, char *argv[]);
 int slave(int argc, char *argv[]);
 int timer(int argc, char *argv[]);
diff --git a/examples/msg/icomms/peer.c b/examples/msg/icomms/peer.c
index a9fa072589..9f882a4f0a 100644
--- a/examples/msg/icomms/peer.c
+++ b/examples/msg/icomms/peer.c
@@ -14,6 +14,17 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ * @section MSG_ex_icomms Asynchronous communications
+ * 
+ * There is several examples of asynchronous communications coming in
+ * the archive. In addition to the fully documented example \ref
+ * MSG_ex_asynchronous_communications, there is several other
+ * examples in the archive:
+ * 
+ * - <b>msg/icomms/peer.c</b>: basic example of async functions (@ref MSG_task_isend, @ref MSG_task_irecv, @ref MSG_comm_wait)
+ */
 int sender(int argc, char *argv[]);
 int receiver(int argc, char *argv[]);
 
diff --git a/examples/msg/icomms/peer2.c b/examples/msg/icomms/peer2.c
index 9e27e9b43b..651e3dbd92 100644
--- a/examples/msg/icomms/peer2.c
+++ b/examples/msg/icomms/peer2.c
@@ -14,6 +14,11 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ * - <b>msg/icomms/peer2.c</b>: demonstrates the @ref MSG_comm_waitall function
+ */
+
 int sender(int argc, char *argv[]);
 int receiver(int argc, char *argv[]);
 
diff --git a/examples/msg/icomms/peer3.c b/examples/msg/icomms/peer3.c
index a86a0cc7ac..128d01f192 100644
--- a/examples/msg/icomms/peer3.c
+++ b/examples/msg/icomms/peer3.c
@@ -14,6 +14,11 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ * - <b>msg/icomms/peer3.c</b>: demonstrates the @ref MSG_comm_waitany function
+ */
+
 int sender(int argc, char *argv[]);
 int receiver(int argc, char *argv[]);
 
diff --git a/examples/msg/io/file.c b/examples/msg/io/file.c
index 69e45db4fa..91c8ee80f8 100644
--- a/examples/msg/io/file.c
+++ b/examples/msg/io/file.c
@@ -4,6 +4,17 @@
 /* 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 MSG_examples
+ * 
+ * @subsection MSG_ex_resources Other resource kinds
+ * 
+ * This section contains some sparse examples of how to use the other
+ * kind of resources, such as disk or GPU. These resources are quite
+ * experimental for now, but here we go anyway.
+ * 
+ * - <b>io/file.c</b> Example with the disk resource
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include "msg/msg.h"
diff --git a/examples/msg/masterslave/masterslave_console.c b/examples/msg/masterslave/masterslave_console.c
index 5b4a1abfec..0b54bfa997 100644
--- a/examples/msg/masterslave/masterslave_console.c
+++ b/examples/msg/masterslave/masterslave_console.c
@@ -1,9 +1,19 @@
-/* Copyright (c) 2007, 2008, 2009, 2010. The SimGrid Team.
- * All rights reserved.                                                     */
+/* Copyright (c) 2007-2012. The SimGrid Team. All rights reserved.          */
 
 /* 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 MSG_examples
+ * 
+ * - <b>masterslave/masterslave_console.c</b>: demonstrate how to use
+ *   lua files instead of XML for the platform and deployment
+ *   declaration using @ref MSG_load_platform_script. The most
+ *   interesting part is probably not the C code, but rather the
+ *   <b>masterslave/masterslave_script.lua</b>, which demonstrates
+ *   how to express the platform and deployment in lua. 
+ *
+ */
+
 #include <stdio.h>
 #include "msg/msg.h"            /* Yeah! If you want to use msg, you need to include msg/msg.h */
 #include "surf/surfxml_parse.h" /* to override surf_parse and bypass the parser */
diff --git a/examples/msg/masterslave/masterslave_forwarder.c b/examples/msg/masterslave/masterslave_forwarder.c
index b428b60ff6..1e0d779dcb 100644
--- a/examples/msg/masterslave/masterslave_forwarder.c
+++ b/examples/msg/masterslave/masterslave_forwarder.c
@@ -14,6 +14,15 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ *  - <b>masterslave/masterslave_forwarder.c: Master/slaves
+ *    example</b>. This good old example is also very simple. Its basic
+ *    version is fully commented on this page: \ref MSG_ex_master_slave,
+ *    but several variants can be found in the same directory. 
+ */
+
+
 int master(int argc, char *argv[]);
 int slave(int argc, char *argv[]);
 int forwarder(int argc, char *argv[]);
diff --git a/examples/msg/masterslave/platform_script.lua b/examples/msg/masterslave/platform_script.lua
index bb1853f3d6..32215a9ef7 100644
--- a/examples/msg/masterslave/platform_script.lua
+++ b/examples/msg/masterslave/platform_script.lua
@@ -1,3 +1,15 @@
+-- Copyright (c) 2010-2012. The SimGrid Team. All rights reserved.
+
+-- 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.
+
+
+-- This file describes a platform very similar to the small_platform.xml, but in lua
+-- It is naturally to be used with the MSG_load_platform_script function
+
+-- Of course, such a flat file is maybe not very interesting wrt xml.
+-- The full power of lua reveals when you describe your platform programatically. 
+
 require "simgrid"
 
   simgrid.AS.new{id="AS0",mode="Full"}; 
diff --git a/examples/msg/migration/migration.c b/examples/msg/migration/migration.c
index cd2b65dbb8..f0ec59694f 100644
--- a/examples/msg/migration/migration.c
+++ b/examples/msg/migration/migration.c
@@ -12,6 +12,13 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ *  
+ *  - <b>migration/migration.c</b> Demonstrates how to use the @ref
+ *    MSG_process_migrate function to let processes change the host they 
+ *    run on after their start. 
+ */
+
 xbt_mutex_t mutex = NULL;
 xbt_cond_t cond = NULL;
 static m_process_t process_to_migrate = NULL;
diff --git a/examples/msg/ns3/ns3.c b/examples/msg/ns3/ns3.c
index 406f07c688..e121a3f2e1 100644
--- a/examples/msg/ns3/ns3.c
+++ b/examples/msg/ns3/ns3.c
@@ -13,6 +13,25 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+
+/** @addtogroup MSG_examples
+ * 
+ *  @section MSG_ex_models Models-related examples
+ * 
+ *  @subsection MSG_ex_PLS Packet level simulators
+ * 
+ *  These examples demonstrate how to use the bindings to classical
+ *  Packet-Level Simulators (PLS), as explained in \ref pls. The most
+ *  interesting is probably not the C files since they are unchanged
+ *  from the other simulations, but the associated files, such as the
+ *  platform files to see how to declare a platform to be used with
+ *  the PLS bindings of SimGrid and the tesh files to see how to
+ *  actually start a simulation in these settings.
+ * 
+ * - <b>ns3</b>: Simple ping-pong using ns3 instead of the SimGrid network models. 
+ * 
+ */
+
 int master(int argc, char *argv[]);
 int slave(int argc, char *argv[]);
 int timer(int argc, char *argv[]);
diff --git a/examples/msg/parallel_task/parallel_task.c b/examples/msg/parallel_task/parallel_task.c
index 11f7251e39..7811e91f1c 100644
--- a/examples/msg/parallel_task/parallel_task.c
+++ b/examples/msg/parallel_task/parallel_task.c
@@ -14,6 +14,16 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ * - <b>parallel_task/parallel_task.c</b>: Demonstrates the use of
+ *   @ref MSG_parallel_task_create, to create special tasks that run
+ *   on several hosts at the same time. The resulting simulations are
+ *   very close to what can be achieved in @ref SD_API, but still
+ *   allows to use the other features of MSG (it'd be cool to be able
+ *   to mix interfaces, but it's not possible ATM).
+ */
+
 int test(int argc, char *argv[]);
 MSG_error_t test_all(const char *platform_file);
 
diff --git a/examples/msg/pmm/msg_pmm.c b/examples/msg/pmm/msg_pmm.c
index 163950ae3d..75d0e6e448 100644
--- a/examples/msg/pmm/msg_pmm.c
+++ b/examples/msg/pmm/msg_pmm.c
@@ -14,6 +14,14 @@
 #include "xbt/xbt_os_time.h"
 #endif
 
+/** @addtogroup MSG_examples
+ * 
+ * - <b>pmm/msg_pmm.c</b>: Parallel Matrix Multiplication is a little
+ *   application. This is something that most MPI developper have
+ *   written during their class, here implemented using MSG instead
+ *   of MPI. 
+ */
+
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_pmm,
                              "Messages specific for this msg example");
 
diff --git a/examples/msg/priority/priority.c b/examples/msg/priority/priority.c
index e4686cbd26..02f0758829 100644
--- a/examples/msg/priority/priority.c
+++ b/examples/msg/priority/priority.c
@@ -14,6 +14,14 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ * - <b>priority/priority.c</b>: Demonstrates the use of @ref
+ *   MSG_task_set_priority to change the computation priority of a
+ *   given task.
+ *
+ */
+
 static int test(int argc, char *argv[])
 {
   double computation_amount = 0.0;
diff --git a/examples/msg/properties/msg_prop.c b/examples/msg/properties/msg_prop.c
index 5f33de9313..63f1e5fdc4 100644
--- a/examples/msg/properties/msg_prop.c
+++ b/examples/msg/properties/msg_prop.c
@@ -14,6 +14,18 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+/** @addtogroup MSG_examples
+ * 
+ * - <b>properties/msg_prop.c</b> Attaching arbitrary informations to
+ *   host, processes and such, and retrieving them with @ref
+ *   MSG_host_get_properties, @ref MSG_host_get_property_value, @ref
+ *   MSG_process_get_properties and @ref
+ *   MSG_process_get_property_value. Also make sure to read the
+ *   platform and deployment XML files to see how to declare these
+ *   data.
+ * 
+ */
+
 XBT_LOG_NEW_DEFAULT_CATEGORY(test, "Property test");
 
 int alice(int argc, char *argv[]);
diff --git a/examples/msg/sendrecv/sendrecv.c b/examples/msg/sendrecv/sendrecv.c
index 56bd3751ba..a59aa5471d 100644
--- a/examples/msg/sendrecv/sendrecv.c
+++ b/examples/msg/sendrecv/sendrecv.c
@@ -13,6 +13,13 @@
 #include "xbt/log.h"
 #include "xbt/asserts.h"
 
+/** @addtogroup MSG_examples
+ * 
+ *  - <b>sendrecv/sendrecv.c: Ping-pong example</b>. It's hard to
+ *    think of a simpler example. The tesh files laying in the
+ *    directory are instructive concerning the way to pass options to the simulators (as described in \ref options).
+ */
+
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
diff --git a/examples/msg/suspend/suspend.c b/examples/msg/suspend/suspend.c
index e1e2ba87a6..a60c03f2b3 100644
--- a/examples/msg/suspend/suspend.c
+++ b/examples/msg/suspend/suspend.c
@@ -12,6 +12,10 @@
 XBT_LOG_NEW_DEFAULT_CATEGORY(msg_test,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ * - <b>suspend/suspend.c</b>: Demonstrates how to suspend and resume processes using @ref MSG_process_suspend and @ref MSG_process_resume.
+ */
 
 /** Lazy guy function. This process suspends itself asap.  */
 static int lazy_guy(int argc, char *argv[])
diff --git a/examples/msg/token_ring/ring_call.c b/examples/msg/token_ring/ring_call.c
index be1b4a7c59..3de124d020 100644
--- a/examples/msg/token_ring/ring_call.c
+++ b/examples/msg/token_ring/ring_call.c
@@ -18,6 +18,16 @@ int nb_hosts; /* All declared hosts */
 XBT_LOG_NEW_DEFAULT_CATEGORY(ring,
                              "Messages specific for this msg example");
 
+/** @addtogroup MSG_examples
+ * 
+ *  @section MSG_ex_apps Examples of full applications
+ * 
+ * - <b>token_ring/ring_call.c</b>: Classical token ring
+ *   communication, where a token is exchanged along a ring to reach
+ *   every participant.
+ * 
+ */
+
 int host(int argc, char *argv[])
 {
   int host_number = atoi(MSG_process_get_name(MSG_process_self()));
diff --git a/examples/msg/tracing/categories.c b/examples/msg/tracing/categories.c
index 3dd29f11f4..314addeab5 100644
--- a/examples/msg/tracing/categories.c
+++ b/examples/msg/tracing/categories.c
@@ -4,6 +4,11 @@
 /* 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 MSG_examples
+ * 
+ * - <b>tracing/categories.c</b> example with the declaration of multiple categories
+ */
+
 #include <stdio.h>
 #include "msg/msg.h"
 #include "xbt/sysdep.h"         /* calloc, printf */
diff --git a/examples/msg/tracing/ms.c b/examples/msg/tracing/ms.c
index bdde3c761e..df58acd05d 100644
--- a/examples/msg/tracing/ms.c
+++ b/examples/msg/tracing/ms.c
@@ -4,6 +4,11 @@
 /* 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 MSG_examples
+ * 
+ * - <b>tracing/ms.c</b> TODO
+ */
+
 #include <stdio.h>
 #include "msg/msg.h"
 #include "xbt/sysdep.h"         /* calloc, printf */
diff --git a/examples/msg/tracing/procmig.c b/examples/msg/tracing/procmig.c
index 3efb25119a..daa14662db 100644
--- a/examples/msg/tracing/procmig.c
+++ b/examples/msg/tracing/procmig.c
@@ -1,8 +1,13 @@
-/* Copyright (c) 2009 The SimGrid team. All rights reserved.                */
+/* Copyright (c) 2010 The SimGrid team. All rights reserved.                */
 
 /* 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 MSG_examples
+ * 
+ * - <b>tracing/procmig.c</b> example to trace process migration using the mask TRACE_PROCESS
+ */
+
 #include "msg/msg.h"            /* core library */
 #include "xbt/sysdep.h"         /* calloc */
 
diff --git a/examples/msg/tracing/simple.c b/examples/msg/tracing/simple.c
index c7619bb067..daaab12344 100644
--- a/examples/msg/tracing/simple.c
+++ b/examples/msg/tracing/simple.c
@@ -8,6 +8,13 @@
 #include "msg/msg.h"
 #include "xbt/sysdep.h"         /* calloc, printf */
 
+/** @addtogroup MSG_examples
+ * 
+ * @section MSG_ex_tracing Tracing and vizualization features
+ * 
+ * - <b>tracing/simple.c</b> very simple program that creates, executes and destroy a task
+ */
+
 /* Create a log channel to have nice outputs. */
 #include "xbt/log.h"
 #include "xbt/asserts.h"
diff --git a/examples/msg/tracing/trace_platform.c b/examples/msg/tracing/trace_platform.c
index 78a48c4bfa..a3e9dd91db 100644
--- a/examples/msg/tracing/trace_platform.c
+++ b/examples/msg/tracing/trace_platform.c
@@ -4,6 +4,11 @@
 /* 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 MSG_examples
+ * 
+ * - <b>tracing/trace_platform.c</b>: Demonstrates how to trace the platform
+ */
+
 #include <stdio.h>
 #include "msg/msg.h"
 #include "xbt/sysdep.h"         /* calloc, printf */
diff --git a/examples/msg/tracing/user_variables.c b/examples/msg/tracing/user_variables.c
index 938e690615..245e02681e 100644
--- a/examples/msg/tracing/user_variables.c
+++ b/examples/msg/tracing/user_variables.c
@@ -4,6 +4,11 @@
 /* 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 MSG_examples
+ * 
+ * - <b>tracing/user_variables.c</b>: Demonstrates how to trace user-provided variables
+ */
+
 #include <stdio.h>
 #include "msg/msg.h"
 #include "xbt/sysdep.h"         /* calloc, printf */