MSG doc tweakings

diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc
index f502bd8..b63e181 100644 (file)
--- a/doc/doxygen/module-msg.doc
+++ b/doc/doxygen/module-msg.doc
@@ -1,25 +1,20 @@
 /**
 /**

-@defgroup MSG_API  MSG: Simple API for Concurrent Sequential Process Algorithms
+@page MSG_API  MSG: Simple API for CSP Algorithms

 @brief Simple programming environment
 
 @brief Simple programming environment
 

-MSG was the first distributed programming environment provided within SimGrid,
-and is still the most commonly used nowadays. If you are unsure of the interface
-you should use, they you probably want to use MSG. It constitutes a convenient
-simplification of the reality of distributed systems. It can be used to build
-rather realistic simulations, but remains simple to use: most unpleasant
-technical elements can be abstracted away rather easily.  If you want to use the
-C programming language, your are in the right section. If you prefer not to use
-this venerable but demanding language, please refer to the @ref MSG_Java section.
-
-If you think that MSG may not be the interface you need, please consider the
-other user interfaces provided by SimGrid: If you want to use DAGs, have a look
-at the \ref SD_API programming environment. If you want to study an existing MPI
-program, have a look at the \ref SMPI_API one. If none of those programming
-environments fits your needs, you may consider implementing your own directly on
-top of \ref SIMIX_API, or even on top of \ref SURF_API (but you want to contact
-us before digging into these badly documented internal modules).
+MSG is a simple API to write algorithms organized with Concurrent
+Sequential Processes (CSP) that interact by exchanging messages. It
+constitutes a convenient simplification of the reality of distributed
+systems. It can be used to build rather realistic simulations, but
+remains simple to use: most unpleasant technical elements can be
+abstracted away rather easily.

 
 

+If you are unsure, then you probably want to use MSG. Otherwise, you
+may want to use one of the following:

 
 

+ - MSG in Java instead of C: @ref MSG_Java.
+ - If you want to use DAGs: @ref SD_API.
+ - If you want to study a MPI application: @ref SMPI_API.

 
 \section MSG_funct Offered functionalities
    - \ref msg_simulation
 
 \section MSG_funct Offered functionalities
    - \ref msg_simulation


@@ -27,18 +22,14 @@ us before digging into these badly documented internal modules).
    - \ref m_host_management
    - \ref m_task_management
    - \ref msg_mailbox_management
    - \ref m_host_management
    - \ref m_task_management
    - \ref msg_mailbox_management

-   - \ref msg_file_management
+   - @ref msg_file

    - \ref msg_task_usage
    - \ref msg_VMs
    - \ref msg_synchro
    - \ref msg_trace_driven
    - \ref MSG_examples
 
    - \ref msg_task_usage
    - \ref msg_VMs
    - \ref msg_synchro
    - \ref msg_trace_driven
    - \ref MSG_examples
 

-
-  Also make sure to visit the page @ref MSG_examples.
-*/
-
-
+*/ 

 
 /**
 @defgroup msg_simulation   Main MSG simulation Functions
 
 /**
 @defgroup msg_simulation   Main MSG simulation Functions


@@ -119,12 +110,10 @@ details).
  *   is based on POSIX functions.
  */
 
  *   is based on POSIX functions.
  */
 

-/** @defgroup msg_file_management File Management Functions
- *  @ingroup MSG_API
- *  @brief This section describes the file structure of MSG
- *         (#msg_file_t) and the functions for managing it. It
- *   is based on POSIX functions.
- */
+/** @defgroup msg_file File Management Functions
+    @ingroup MSG_API
+    @brief MSG files (#msg_file_t) and associated functions, inspired from POSIX file handling.
+*/

 
 /**
 @defgroup msg_trace_driven Trace-driven simulations
 
 /**
 @defgroup msg_trace_driven Trace-driven simulations

diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc
index 1d8d553..963f3cc 100644 (file)
--- a/doc/doxygen/platform.doc
+++ b/doc/doxygen/platform.doc
@@ -694,8 +694,8 @@ id              | yes       | string | Name of the link that is supposed to act
   is just some doc valuable only at the time of writing.
   This section describes the storage management under SimGrid ; nowadays
   it's only usable with MSG. It relies basically on linux-like concepts.
   is just some doc valuable only at the time of writing.
   This section describes the storage management under SimGrid ; nowadays
   it's only usable with MSG. It relies basically on linux-like concepts.

-  You also may want to have a look to its corresponding section in \ref
-  msg_file_management ; access functions are organized as a POSIX-like
+  You also may want to have a look to its corresponding section in 
+  @ref msg-file-page ; access functions are organized as a POSIX-like

   interface.
 
 \subsubsection pf_sto_conc Storage - Main Concepts
   interface.
 
 \subsubsection pf_sto_conc Storage - Main Concepts

diff --git a/include/simgrid/msg.h b/include/simgrid/msg.h
index d2450b4..cf51190 100644 (file)
--- a/include/simgrid/msg.h
+++ b/include/simgrid/msg.h
@@ -79,13 +79,10 @@ typedef struct msg_task *msg_task_t;
 /* ******************************** VM ************************************* */
 typedef msg_host_t msg_vm_t;
 
 /* ******************************** VM ************************************* */
 typedef msg_host_t msg_vm_t;
 

-/** ******************************** File ************************************ */
+/* ******************************** File ************************************ */

 
 

-/** @brief File datatype.
-*  @ingroup msg_file_management
-*
-*  You should consider this as an opaque object.
-*/
+/** @brief Opaque object describing a File in MSG.
+ *  @ingroup msg_file */

 typedef xbt_dictelm_t msg_file_t;
 typedef s_xbt_dictelm_t s_msg_file_t;
 
 typedef xbt_dictelm_t msg_file_t;
 typedef s_xbt_dictelm_t s_msg_file_t;
 

diff --git a/src/msg/msg_io.cpp b/src/msg/msg_io.cpp
index efd19a7..845998b 100644 (file)
--- a/src/msg/msg_io.cpp
+++ b/src/msg/msg_io.cpp
@@ -9,7 +9,7 @@
 
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_io, msg, "Logging specific to MSG (io)");
 
 
 XBT_LOG_NEW_DEFAULT_SUBCATEGORY(msg_io, msg, "Logging specific to MSG (io)");
 

-/** @addtogroup msg_file_management
+/** @addtogroup msg_file

  * (#msg_file_t) and the functions for managing it.
  *
  *  \see #msg_file_t
  * (#msg_file_t) and the functions for managing it.
  *
  *  \see #msg_file_t


@@ -32,7 +32,7 @@ void __MSG_file_get_info(msg_file_t fd){
   xbt_dynar_free_container(&info);
 }
 
   xbt_dynar_free_container(&info);
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  *
  * \brief Set the user data of a #msg_file_t.
  *
  *
  * \brief Set the user data of a #msg_file_t.
  *


@@ -45,7 +45,7 @@ msg_error_t MSG_file_set_data(msg_file_t fd, void *data)
   return MSG_OK;
 }
 
   return MSG_OK;
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  *
  * \brief Return the user data of a #msg_file_t.
  *
  *
  * \brief Return the user data of a #msg_file_t.
  *


@@ -57,7 +57,7 @@ void *MSG_file_get_data(msg_file_t fd)
   return priv->data;
 }
 
   return priv->data;
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  * \brief Display information related to a file descriptor
  *
  * \param fd is a the file descriptor
  * \brief Display information related to a file descriptor
  *
  * \param fd is a the file descriptor


@@ -80,7 +80,7 @@ void MSG_file_dump (msg_file_t fd){
            priv->content_type, priv->desc_id);
 }
 
            priv->content_type, priv->desc_id);
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  * \brief Read a file (local or remote)
  *
  * \param size of the file to read
  * \brief Read a file (local or remote)
  *
  * \param size of the file to read


@@ -126,7 +126,7 @@ sg_size_t MSG_file_read(msg_file_t fd, sg_size_t size)
   return read_size;
 }
 
   return read_size;
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  * \brief Write into a file (local or remote)
  *
  * \param size of the file to write
  * \brief Write into a file (local or remote)
  *
  * \param size of the file to write


@@ -176,7 +176,7 @@ sg_size_t MSG_file_write(msg_file_t fd, sg_size_t size)
   return write_size;
 }
 
   return write_size;
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  * \brief Opens the file whose name is the string pointed to by path
  *
  * \param fullpath is the file location on the storage
  * \brief Opens the file whose name is the string pointed to by path
  *
  * \param fullpath is the file location on the storage


@@ -204,7 +204,7 @@ msg_file_t MSG_file_open(const char* fullpath, void* data)
   return fd;
 }
 
   return fd;
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  * \brief Close the file
  *
  * \param fd is the file to close
  * \brief Close the file
  *
  * \param fd is the file to close


@@ -225,7 +225,7 @@ int MSG_file_close(msg_file_t fd)
   return res;
 }
 
   return res;
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  * \brief Unlink the file pointed by fd
  *
  * \param fd is the file descriptor (#msg_file_t)
  * \brief Unlink the file pointed by fd
  *
  * \param fd is the file descriptor (#msg_file_t)


@@ -243,7 +243,7 @@ msg_error_t MSG_file_unlink(msg_file_t fd)
   return (msg_error_t) res;
 }
 
   return (msg_error_t) res;
 }
 

-/** \ingroup msg_file_management
+/** \ingroup msg_file

  * \brief Return the size of a file
  *
  * \param fd is the file descriptor (#msg_file_t)
  * \brief Return the size of a file
  *
  * \param fd is the file descriptor (#msg_file_t)


@@ -255,7 +255,7 @@ sg_size_t MSG_file_get_size(msg_file_t fd){
 }
 
 /**
 }
 
 /**

- * \ingroup msg_file_management
+ * \ingroup msg_file

  * \brief Set the file position indicator in the msg_file_t by adding offset bytes
  * to the position specified by origin (either SEEK_SET, SEEK_CUR, or SEEK_END).
  *
  * \brief Set the file position indicator in the msg_file_t by adding offset bytes
  * to the position specified by origin (either SEEK_SET, SEEK_CUR, or SEEK_END).
  *


@@ -273,7 +273,7 @@ msg_error_t MSG_file_seek(msg_file_t fd, sg_offset_t offset, int origin)
 }
 
 /**
 }
 
 /**

- * \ingroup msg_file_management
+ * \ingroup msg_file

  * \brief Returns the current value of the position indicator of the file
  *
  * \param fd : file object that identifies the stream
  * \brief Returns the current value of the position indicator of the file
  *
  * \param fd : file object that identifies the stream


@@ -293,7 +293,7 @@ const char *MSG_file_get_name(msg_file_t fd) {
 }
 
 /**
 }
 
 /**

- * \ingroup msg_file_management
+ * \ingroup msg_file

  * \brief Move a file to another location on the *same mount point*.
  *
  */
  * \brief Move a file to another location on the *same mount point*.
  *
  */


@@ -304,7 +304,7 @@ msg_error_t MSG_file_move (msg_file_t fd, const char* fullpath)
 }
 
 /**
 }
 
 /**

- * \ingroup msg_file_management
+ * \ingroup msg_file

  * \brief Copy a file to another location on a remote host.
  * \param file : the file to move
  * \param host : the remote host where the file has to be copied
  * \brief Copy a file to another location on a remote host.
  * \param file : the file to move
  * \param host : the remote host where the file has to be copied


@@ -388,7 +388,7 @@ msg_error_t MSG_file_rcopy (msg_file_t file, msg_host_t host, const char* fullpa
 }
 
 /**
 }
 
 /**

- * \ingroup msg_file_management
+ * \ingroup msg_file

  * \brief Move a file to another location on a remote host.
  * \param file : the file to move
  * \param host : the remote host where the file has to be moved
  * \brief Move a file to another location on a remote host.
  * \param file : the file to move
  * \param host : the remote host where the file has to be moved