Improve MSG doc a bit

It is impossible to document lua modules with doxygen so far, so don't
do a submenu to separate the C interface from the lua one, but add a
word about lua in a unique page, under MSG.

The C interface moves up directly under MSG, without any MSG_C in the
middle.

Move all MSG module creations into module-MSG.doc for simplicity (and
because this is the only way to finely control their order).

Also, drop channel documentation.

diff --git a/doc/module-msg.doc b/doc/module-msg.doc
index cdad6be..e5c5549 100644 (file)
--- a/doc/module-msg.doc
+++ b/doc/module-msg.doc
@@ -1,10 +1,5 @@
+/** \addtogroup MSG_API

 
 

-/** \defgroup MSG_C      MSG native
-    \ingroup MSG_API
-    \brief Native interface to MSG (\ref MSG_API)
-
-    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Native interface" --> \endhtmlonly 
-         

       MSG was the first distributed programming environment provided within
       SimGrid. While almost realistic, it remains quite simple (simplistic?).
       This describes the native to MSG.
       MSG was the first distributed programming environment provided within
       SimGrid. While almost realistic, it remains quite simple (simplistic?).
       This describes the native to MSG.


@@ -16,33 +11,6 @@
       use the C programming language, your are in the right
       section. To use the Java or Ruby programming interfaces, please refer to
       the documentation provided in the relevant packages.
       use the C programming language, your are in the right
       section. To use the Java or Ruby programming interfaces, please refer to
       the documentation provided in the relevant packages.

-*/
-
-
-/**
-
-\defgroup MSG_LUA      lMSG
-    \ingroup MSG_API
-    \brief Lua bindings to MSG (\ref MSG_API)
-
-    \htmlonly <!-- 
-      DOXYGEN_NAVBAR_LABEL="LUA bindings" 
-    --> \endhtmlonly 
-         
-      MSG was the first distributed programming environment provided within
-      SimGrid. While almost realistic, it remains quite simple (simplistic?).
-      This describes the Lua bindings to this interface.
-
-      \section lMSG_who Who should use this (and who shouldn't)
-      
-      You should use MSG if you want to study some heuristics for a
-      given problem you don't really want to implement. If you want to
-      use the Lua script language, your are in the right
-      section. To use the C interface, please refer to \ref MSG_C.
-
-*/
-
-/** @addtogroup MSG_C

 
   \section MSG_funct Offered functionnalities
    - \ref m_process_management
 
   \section MSG_funct Offered functionnalities
    - \ref m_process_management


@@ -50,7 +18,6 @@
    - \ref m_host_management
    - \ref m_task_management
    - \ref msg_gos_functions
    - \ref m_host_management
    - \ref m_task_management
    - \ref msg_gos_functions

-   - \ref m_channel_management

    - \ref msg_easier_life
    - \ref msg_simulation
 
    - \ref msg_easier_life
    - \ref msg_simulation
 


@@ -61,41 +28,92 @@
    - \ref MSG_ex_master_slave_scrip_lua
 */
 
    - \ref MSG_ex_master_slave_scrip_lua
 */
 

-/** @addtogroup MSG_LUA
+
+/** @defgroup m_datatypes_management MSG Data Types 
+    @ingroup MSG_API
+    @brief This section describes the different datatypes provided by MSG.
+    
+    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Data types" --> \endhtmlonly
+*/
+
+/** @defgroup m_process_management Management Functions of Agents
+ *  @ingroup MSG_API
+ *  @brief This section describes the agent structure of MSG
+ *         (#m_process_t) and the functions for managing it.
+ */
+   
+/** @defgroup m_host_management Management functions of Hosts
+ *  @ingroup MSG_API
+ *  @brief This section describes the host structure of MSG
+ */
+  
+/** @defgroup m_task_management Managing functions of Tasks
+ *  @ingroup MSG_API
+ *  @brief This section describes the task structure of MSG
+ *         (#m_task_t) and the functions for managing it.
+ */
+   
+/** @defgroup msg_gos_functions MSG Operating System Functions
+ *  @ingroup MSG_API
+ *  @brief This section describes the functions that can be used
+ *         by an agent for handling some task.
+ */
+
+/** @defgroup msg_easier_life      Platform and Application management
+ *  @ingroup MSG_API
+ *  @brief This section describes functions to manage the platform creation
+ *         and the application deployment. Please check @ref
+ *         MSG_examples for an overview of their usage. 
+ */
+ 
+/** 
+@defgroup msg_simulation   MSG simulation Functions
+@ingroup MSG_API
+@brief This section describes the functions you need to know to
+       set up a simulation. You should have a look at \ref MSG_examples
+       to have an overview of their usage.
+
+@htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation functions" --> @endhtmlonly
+*/
+ 
+/**
+@defgroup MSG_LUA      Lua bindings
+@ingroup MSG_API
+@brief Lua bindings to MSG (\ref MSG_API)
+
+@htmlonly <!--  DOXYGEN_NAVBAR_LABEL="LUA bindings" --> @endhtmlonly 
+         
+      This is the lua bindings of the \ref MSG_API interface.
+
+      \section lMSG_who Who should use this (and who shouldn't)
+      
+      If you want to use MSG to study your algorithm, but you don't
+      want to use the C language (using \ref MSG_API), then you should
+      use some bindings such as this one. The advantage of the lua
+      bindings is that they are distributed directly with the main
+      archive (in contrary to Java and Ruby bindings, for example,
+      that are distributed separately). Another advantage of lua is
+      that there is almost no performance loss with regard to the C
+      version (at least there shouln't be any -- it is still to be
+      precisely assessed).

 
   \section MSG_Lua_funct  Lua offered functionnalities in MSG
 
   \section MSG_Lua_funct  Lua offered functionnalities in MSG

-   - \ref lua_host_management
-   - \ref lua_tasks_management
-   - \ref lua_environment_management
+  Almost all important features of the MSG interface are available
+  from the lua bindings. Unfortunately, since doxygen does not support
+  the lua modules implemented directly in C as we are using, there is
+  no ready to use reference documentation for this module. Even more
+  than for the other modules, you will have to dig into the source
+  code of the examples to learn how to use it. 
+

   \section Lua_examples Examples of lua MSG
  
    - \ref MSG_ex_master_slave_lua
    - \ref MSG_ex_master_slave_lua_bypass
   \section Lua_examples Examples of lua MSG
  
    - \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

 */
 
 
 */
 
 

-/** @defgroup m_datatypes_management MSG Data Types 
-    @ingroup MSG_C
-    @brief This section describes the different datatypes provided by MSG.
-    
-    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Data types" --> \endhtmlonly
-*/
-/**     \addtogroup m_process_management
-        \ingroup MSG_C  */
-/**     \addtogroup m_host_management
-        \ingroup MSG_C  */
-/**     \addtogroup m_task_management
-        \ingroup MSG_C  */
-/**     \addtogroup msg_gos_functions
-        \ingroup MSG_C  */
-/**     \addtogroup m_channel_management
-        \ingroup MSG_C  */
-/**     \addtogroup msg_easier_life
-        \ingroup MSG_C  */
-/**     \addtogroup msg_simulation
-        \ingroup MSG_C  */
-
-

 /** \page MSG_ex_asynchronous_communications Asynchronous communication applications
 
     Simulation of asynchronous communications between a sender and a receiver using a realistic platform and
 /** \page MSG_ex_asynchronous_communications Asynchronous communication applications
 
     Simulation of asynchronous communications between a sender and a receiver using a realistic platform and


@@ -496,3 +514,4 @@
       \until simgrid.clean()
       
 */
       \until simgrid.clean()
       
 */

+

diff --git a/src/msg/msg_environment.c b/src/msg/msg_environment.c
index 6d598d6..d4786a7 100644 (file)
--- a/src/msg/msg_environment.c
+++ b/src/msg/msg_environment.c
@@ -13,12 +13,7 @@
 #include <lauxlib.h>
 #include <lualib.h>
 #endif
 #include <lauxlib.h>
 #include <lualib.h>
 #endif

-//#endif
-/** \defgroup msg_easier_life      Platform and Application management
- *  \brief This section describes functions to manage the platform creation
- *  and the application deployment. You should also have a look at 
- *  \ref MSG_examples  to have an overview of their usage.
- */
+

 /** @addtogroup msg_easier_life
  *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Platforms and Applications" --> \endhtmlonly
  * 
 /** @addtogroup msg_easier_life
  *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Platforms and Applications" --> \endhtmlonly
  * 

diff --git a/src/msg/msg_global.c b/src/msg/msg_global.c
index 1cfcfa3..c305f4e 100644 (file)
--- a/src/msg/msg_global.c
+++ b/src/msg/msg_global.c
@@ -17,16 +17,6 @@ XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_kernel, msg,
 
 MSG_Global_t msg_global = NULL;
 
 
 MSG_Global_t msg_global = NULL;
 

-
-/** \defgroup msg_simulation   MSG simulation Functions
- *  \brief This section describes the functions you need to know to
- *  set up a simulation. You should have a look at \ref MSG_examples
- *  to have an overview of their usage.
- */
-/** @addtogroup msg_simulation
- *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Simulation functions" --> \endhtmlonly
- */
-

 /********************************* MSG **************************************/
 
 /** \ingroup msg_simulation
 /********************************* MSG **************************************/
 
 /** \ingroup msg_simulation


@@ -88,25 +78,8 @@ void MSG_global_init(int *argc, char **argv)
 }
 
 #ifdef MSG_USE_DEPRECATED
 }
 
 #ifdef MSG_USE_DEPRECATED

-/** \defgroup m_channel_management    Understanding channels
- *  \brief This section briefly describes the channel notion of MSG
- *  (#m_channel_t).
- */
-/** @addtogroup m_channel_management
- *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Channels" --> \endhtmlonly
- *
- *
- *  For convenience, the simulator provides the notion of channel
- *  that is close to the tag notion in MPI. A channel is not a
- *  socket. It doesn't need to be opened neither closed. It rather
- *  corresponds to the ports opened on the different machines.
- */
-

 
 

-/** \ingroup m_channel_management
- * \brief Set the number of channel in the simulation.
- *
- * This function has to be called to fix the number of channel in the
+/* This deprecated function has to be called to fix the number of channel in the

    simulation before creating any host. Indeed, each channel is
    represented by a different mailbox on each #m_host_t. This
    function can then be called only once. This function takes only one
    simulation before creating any host. Indeed, each channel is
    represented by a different mailbox on each #m_host_t. This
    function can then be called only once. This function takes only one


@@ -115,7 +88,7 @@ void MSG_global_init(int *argc, char **argv)
  */
 MSG_error_t MSG_set_channel_number(int number)
 {
  */
 MSG_error_t MSG_set_channel_number(int number)
 {

-  XBT_WARN("DEPRECATED! Now use alias");
+  XBT_WARN("DEPRECATED! Please use aliases instead");

   xbt_assert((msg_global)
               && (msg_global->max_channel == 0),
               "Channel number already set!");
   xbt_assert((msg_global)
               && (msg_global->max_channel == 0),
               "Channel number already set!");


@@ -125,16 +98,13 @@ MSG_error_t MSG_set_channel_number(int number)
   return MSG_OK;
 }
 
   return MSG_OK;
 }
 

-/** \ingroup m_channel_management
- * \brief Return the number of channel in the simulation.
- *
- * This function has to be called once the number of channel is fixed. I can't
+/* This deprecated function has to be called once the number of channel is fixed. I can't

    figure out a reason why anyone would like to call this function but nevermind.
  * \return the number of channel in the simulation.
  */
 int MSG_get_channel_number(void)
 {
    figure out a reason why anyone would like to call this function but nevermind.
  * \return the number of channel in the simulation.
  */
 int MSG_get_channel_number(void)
 {

-  XBT_WARN("DEPRECATED! Now use alias");
+  XBT_WARN("DEPRECATED! Please use aliases instead");

   xbt_assert((msg_global)
               && (msg_global->max_channel != 0),
               "Channel number not set yet!");
   xbt_assert((msg_global)
               && (msg_global->max_channel != 0),
               "Channel number not set yet!");

diff --git a/src/msg/msg_gos.c b/src/msg/msg_gos.c
index 5cd5b90..d76eabe 100644 (file)
--- a/src/msg/msg_gos.c
+++ b/src/msg/msg_gos.c
@@ -994,11 +994,6 @@ MSG_task_get_with_timeout(m_task_t * task, m_channel_t channel,
   return MSG_task_get_ext(task, channel, max_duration, NULL);
 }
 
   return MSG_task_get_ext(task, channel, max_duration, NULL);
 }
 

-/** \defgroup msg_gos_functions MSG Operating System Functions
- *  \brief This section describes the functions that can be used
- *  by an agent for handling some task.
- */
-

 MSG_error_t
 MSG_task_get_ext(m_task_t * task, m_channel_t channel, double timeout,
                  m_host_t host)
 MSG_error_t
 MSG_task_get_ext(m_task_t * task, m_channel_t channel, double timeout,
                  m_host_t host)

diff --git a/src/msg/msg_host.c b/src/msg/msg_host.c
index 9f35815..0dfb100 100644 (file)
--- a/src/msg/msg_host.c
+++ b/src/msg/msg_host.c
@@ -9,9 +9,6 @@
 #include "xbt/sysdep.h"
 #include "xbt/log.h"
 
 #include "xbt/sysdep.h"
 #include "xbt/log.h"
 

-/** \defgroup m_host_management Management functions of Hosts
- *  \brief This section describes the host structure of MSG
- */

 /** @addtogroup m_host_management
  *     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Hosts" --> \endhtmlonly
  * (#m_host_t) and the functions for managing it.
 /** @addtogroup m_host_management
  *     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Hosts" --> \endhtmlonly
  * (#m_host_t) and the functions for managing it.

diff --git a/src/msg/msg_process.c b/src/msg/msg_process.c
index a50ef41..d8fa002 100644 (file)
--- a/src/msg/msg_process.c
+++ b/src/msg/msg_process.c
@@ -11,10 +11,6 @@
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_process, msg,
                                 "Logging specific to MSG (process)");
 
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_process, msg,
                                 "Logging specific to MSG (process)");
 

-/** \defgroup m_process_management Management Functions of Agents
- *  \brief This section describes the agent structure of MSG
- *  (#m_process_t) and the functions for managing it.
- */

 /** @addtogroup m_process_management
  *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Agents" --> \endhtmlonly
  *
 /** @addtogroup m_process_management
  *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Agents" --> \endhtmlonly
  *

diff --git a/src/msg/msg_task.c b/src/msg/msg_task.c
index 20f25d4..da19e1b 100644 (file)
--- a/src/msg/msg_task.c
+++ b/src/msg/msg_task.c
@@ -8,10 +8,6 @@
 #include "xbt/sysdep.h"
 #include "xbt/log.h"
 
 #include "xbt/sysdep.h"
 #include "xbt/log.h"
 

-/** \defgroup m_task_management Managing functions of Tasks
- *  \brief This section describes the task structure of MSG
- *  (#m_task_t) and the functions for managing it.
- */

 /** @addtogroup m_task_management
  *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Tasks" --> \endhtmlonly
  * 
 /** @addtogroup m_task_management
  *    \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="Tasks" --> \endhtmlonly
  *