From 36dffb4f8633c75ddaf66e398f432a8485e9e419 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Tue, 20 Mar 2012 17:00:44 +0100 Subject: [PATCH 1/1] 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. --- doc/module-msg.doc | 139 ++++++++++++++++++++++---------------- src/msg/msg_environment.c | 7 +- src/msg/msg_global.c | 38 ++--------- src/msg/msg_gos.c | 5 -- src/msg/msg_host.c | 3 - src/msg/msg_process.c | 4 -- src/msg/msg_task.c | 4 -- 7 files changed, 84 insertions(+), 116 deletions(-) diff --git a/doc/module-msg.doc b/doc/module-msg.doc index cdad6beaf3..e5c554933b 100644 --- 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 \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. @@ -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. -*/ - - -/** - -\defgroup MSG_LUA lMSG - \ingroup MSG_API - \brief Lua bindings to MSG (\ref MSG_API) - - \htmlonly \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 @@ -50,7 +18,6 @@ - \ref m_host_management - \ref m_task_management - \ref msg_gos_functions - - \ref m_channel_management - \ref msg_easier_life - \ref msg_simulation @@ -61,41 +28,92 @@ - \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 \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 @endhtmlonly +*/ + +/** +@defgroup MSG_LUA Lua bindings +@ingroup MSG_API +@brief Lua bindings to MSG (\ref MSG_API) + +@htmlonly @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 - - \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 + - 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 \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 @@ -496,3 +514,4 @@ \until simgrid.clean() */ + diff --git a/src/msg/msg_environment.c b/src/msg/msg_environment.c index 6d598d62ed..d4786a7585 100644 --- a/src/msg/msg_environment.c +++ b/src/msg/msg_environment.c @@ -13,12 +13,7 @@ #include #include #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 \endhtmlonly * diff --git a/src/msg/msg_global.c b/src/msg/msg_global.c index 1cfcfa3ccf..c305f4e0d5 100644 --- 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; - -/** \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 \endhtmlonly - */ - /********************************* MSG **************************************/ /** \ingroup msg_simulation @@ -88,25 +78,8 @@ void MSG_global_init(int *argc, char **argv) } #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 \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 @@ -115,7 +88,7 @@ void MSG_global_init(int *argc, char **argv) */ 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!"); @@ -125,16 +98,13 @@ MSG_error_t MSG_set_channel_number(int number) 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) { - 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!"); diff --git a/src/msg/msg_gos.c b/src/msg/msg_gos.c index 5cd5b9020e..d76eabe61a 100644 --- 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); } -/** \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) diff --git a/src/msg/msg_host.c b/src/msg/msg_host.c index 9f35815ec0..0dfb1006fe 100644 --- a/src/msg/msg_host.c +++ b/src/msg/msg_host.c @@ -9,9 +9,6 @@ #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 \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 a50ef41e50..d8fa002494 100644 --- 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)"); -/** \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 \endhtmlonly * diff --git a/src/msg/msg_task.c b/src/msg/msg_task.c index 20f25d4afa..da19e1bf59 100644 --- a/src/msg/msg_task.c +++ b/src/msg/msg_task.c @@ -8,10 +8,6 @@ #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 \endhtmlonly * -- 2.20.1