From 838bbd9eea107415d66dd0cdce5098832ba4e6bd Mon Sep 17 00:00:00 2001
From: Martin Quinson <martin.quinson@loria.fr>
Date: Tue, 3 Apr 2012 17:31:02 -1000
Subject: [PATCH] improve doc of trace-driven simulations

---
 doc/module-msg.doc    | 31 ++++++++++++++++++++++++++-----
 src/msg/msg_actions.c |  6 +++---
 src/msg/msg_process.c |  2 +-
 3 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/doc/module-msg.doc b/doc/module-msg.doc
index cd7ae3a6ea..5c7a3e256d 100644
--- a/doc/module-msg.doc
+++ b/doc/module-msg.doc
@@ -18,7 +18,7 @@
    - \ref m_host_management
    - \ref m_task_management
    - \ref m_file_management
-   - \ref msg_actions_functions
+   - \ref msg_trace_driven
    - \ref msg_gos_functions
    - \ref msg_deprecated_functions
    - \ref msg_simulation
@@ -30,6 +30,8 @@
 @defgroup MSG_examples MSG Examples
 @ingroup MSG_API
  
+@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Examples" --> @endhtmlonly
+
 MSG comes with an extensive set of examples. It is sometimes difficult
 to find the one you need. This list aims at helping you finding the
 example from which you can learn what you want to.
@@ -56,7 +58,7 @@ details).
  -# Cleanup the library with #MSG_clean before ending your program
     (optional).
 
-@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation control" --> @endhtmlonly
+@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation Control" --> @endhtmlonly
 */
 
 
@@ -91,9 +93,28 @@ details).
  *   is based on POSIX functions.
  */ 
  
-/** @defgroup msg_actions_functions Managing actions
- *  @ingroup MSG_API
- *  @brief This section describes functions for managing actions.
+/** 
+@defgroup msg_trace_driven Trace-driven simulations
+@ingroup MSG_API
+@brief This section describes the functions allowing to build trace-driven simulations.
+
+\htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Trace-Driven" --> \endhtmlonly
+
+This 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 #MSG_action_register in your main,
+and then use #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 examples in <b>examples/msg/actions/actions.c</b> for details.
+ 
  */ 
 
 /** @defgroup msg_gos_functions MSG Operating System Functions
diff --git a/src/msg/msg_actions.c b/src/msg/msg_actions.c
index 3de164a6cd..a5424c4a0e 100644
--- a/src/msg/msg_actions.c
+++ b/src/msg/msg_actions.c
@@ -24,7 +24,7 @@ static size_t action_len = 0;
 
 static const char **action_get_action(char *name);
 
-/** \ingroup msg_actions_functions
+/** \ingroup msg_trace_driven
  * \brief Registers a function to handle a kind of action
  *
  * Registers a function to handle a kind of action
@@ -40,7 +40,7 @@ void MSG_action_register(const char *action_name, msg_action_fun function)
   xbt_dict_set(action_funs, action_name, function, NULL);
 }
 
-/** \ingroup msg_actions_functions
+/** \ingroup msg_trace_driven
  * \brief Unregisters a function, which handled a kind of action
  *
  * \param action_name the reference name of the action.
@@ -157,7 +157,7 @@ todo_done:
   return NULL;
 }
 
-/** \ingroup msg_actions_functions
+/** \ingroup msg_trace_driven
  * \brief A trace loader
  *
  *  If path!=NULL, load a trace file containing actions, and execute them.
diff --git a/src/msg/msg_process.c b/src/msg/msg_process.c
index d478050cc3..df2bf648ce 100644
--- a/src/msg/msg_process.c
+++ b/src/msg/msg_process.c
@@ -12,7 +12,7 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_process, msg,
                                 "Logging specific to MSG (process)");
 
 /** @addtogroup m_process_management
- *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Process" --> \endhtmlonly
+ *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Processes" --> \endhtmlonly
  *
  *  We need to simulate many independent scheduling decisions, so
  *  the concept of <em>process</em> is at the heart of the
-- 
2.20.1