From b64fe8c6295834b8b526b74509f96094bf9baafd Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sat, 21 May 2016 06:08:18 +0200 Subject: [PATCH 1/1] MSG doc tweakings --- doc/doxygen/module-msg.doc | 47 +++++++++++++++----------------------- doc/doxygen/platform.doc | 4 ++-- include/simgrid/msg.h | 9 +++----- src/msg/msg_io.cpp | 30 ++++++++++++------------ 4 files changed, 38 insertions(+), 52 deletions(-) diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc index f502bd8e15..b63e181495 100644 --- 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 -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 @@ -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 msg_file_management + - @ref msg_file - \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 @@ -119,12 +110,10 @@ details). * 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 diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index 1d8d5533d5..963f3cc73a 100644 --- 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. - 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 diff --git a/include/simgrid/msg.h b/include/simgrid/msg.h index d2450b4701..cf5119057b 100644 --- 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; -/** ******************************** 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; diff --git a/src/msg/msg_io.cpp b/src/msg/msg_io.cpp index efd19a7cea..845998bc7e 100644 --- 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)"); -/** @addtogroup msg_file_management +/** @addtogroup msg_file * (#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); } -/** \ingroup msg_file_management +/** \ingroup msg_file * * \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; } -/** \ingroup msg_file_management +/** \ingroup msg_file * * \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; } -/** \ingroup msg_file_management +/** \ingroup msg_file * \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); } -/** \ingroup msg_file_management +/** \ingroup msg_file * \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; } -/** \ingroup msg_file_management +/** \ingroup msg_file * \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; } -/** \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 @@ -204,7 +204,7 @@ msg_file_t MSG_file_open(const char* fullpath, void* data) return fd; } -/** \ingroup msg_file_management +/** \ingroup msg_file * \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; } -/** \ingroup msg_file_management +/** \ingroup msg_file * \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; } -/** \ingroup msg_file_management +/** \ingroup msg_file * \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). * @@ -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 @@ -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*. * */ @@ -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 @@ -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 -- 2.20.1