From: navarro <navarro@caraja.(none)>
Date: Fri, 23 Mar 2012 10:32:38 +0000 (+0100)
Subject: Write doc for MSG_file function.
X-Git-Tag: v3_7~246
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/1b8282670ce916ad31b361062082096ea32dbc14

Write doc for MSG_file function.
---

diff --git a/doc/module-msg.doc b/doc/module-msg.doc
index 5a5ccb37ef..0abac29301 100644
--- a/doc/module-msg.doc
+++ b/doc/module-msg.doc
@@ -17,6 +17,7 @@
    - \ref m_datatypes_management
    - \ref m_host_management
    - \ref m_task_management
+   - \ref m_file_management
    - \ref msg_gos_functions
    - \ref msg_easier_life
    - \ref msg_simulation
@@ -48,7 +49,14 @@
  *  @brief This section describes the task structure of MSG
  *         (#m_task_t) and the functions for managing it.
  */
-   
+ 
+ /** @defgroup m_file_management Managing functions of Files
+ *  @ingroup MSG_API
+ *  @brief This section describes the file structure of MSG
+ *         (#m_file_t) and the functions for managing it. It
+ *   is based on POSIX functions.
+ */  
+ 
 /** @defgroup msg_gos_functions MSG Operating System Functions
  *  @ingroup MSG_API
  *  @brief This section describes the functions that can be used
diff --git a/src/msg/msg_io.c b/src/msg/msg_io.c
index d7486cfcd7..3d93df607f 100644
--- a/src/msg/msg_io.c
+++ b/src/msg/msg_io.c
@@ -6,28 +6,87 @@
 
 #include "msg_private.h"
 
-// FILE
+/** @addtogroup m_file_management
+ *     \htmlonly <!-- DOXYGEN_NAVBAR_LABEL="File" --> \endhtmlonly
+ * (#m_file_t) and the functions for managing it.
+ *
+ *  \see m_file_t
+ */
 
+/********************************* File **************************************/
+
+/** \ingroup m_file_management
+ * \brief Read elements of a file
+ *
+ * \param storage is the name where find the stream
+ * \param ptr buffer to where the data is copied
+ * \param size of each element
+ * \param nmemb is the number of elements of data to read
+ * \param stream to read
+ * \return the number of items successfully read
+ */
 size_t MSG_file_read(const char* storage, void* ptr, size_t size, size_t nmemb,  m_file_t stream)
 {
   return simcall_file_read(storage, ptr, size, nmemb, (smx_file_t)stream);
 }
 
+/** \ingroup m_file_management
+ * \brief Write elements into a file
+ *
+ * \param storage is the name where find the stream
+ * \param ptr buffer from where the data is copied
+ * \param size of each element
+ * \param nmemb is the number of elements of data to write
+ * \param stream to write
+ * \return the number of items successfully write
+ */
 size_t MSG_file_write(const char* storage, const void* ptr, size_t size, size_t nmemb, m_file_t stream)
 {
   return simcall_file_write(storage, ptr, size, nmemb, (smx_file_t)stream);
 }
 
+/** \ingroup m_file_management
+ * \brief Opens the file whose name is the string pointed to by path
+ *
+ * \param storage is the name where find the file to open
+ * \param path is the file location on the storage
+ * \param mode points to a string beginning with one of the following sequences (Additional characters may follow these sequences.):
+ *      r      Open text file for reading.  The stream is positioned at the beginning of the file.
+ *      r+     Open for reading and writing.  The stream is positioned at the beginning of the file.
+ *      w      Truncate file to zero length or create text file for writing.  The stream is positioned at the beginning of the file.
+ *      w+     Open for reading and writing.  The file is created if it does not exist, otherwise it is truncated.  The stream is positioned at the begin‐
+ *             ning of the file.
+ *      a      Open for appending (writing at end of file).  The file is created if it does not exist.  The stream is positioned at the end of the file.
+ *      a+     Open for reading and appending (writing at end of file).  The file is created if it does not exist.  The initial file position for  reading
+ *             is at the beginning of the file, but output is always appended to the end of the file.
+ *
+ * \return A m_file_t associated to the file
+ */
 m_file_t MSG_file_open(const char* storage, const char* path, const char* mode)
 {
   return (m_file_t) simcall_file_open(storage, path, mode);
 }
 
+/** \ingroup m_file_management
+ * \brief Close the file
+ *
+ * \param storage is the name where find the stream
+ * \param fp is the file to close
+ * \return 0 on success or 1 on error
+ */
 int MSG_file_close(const char* storage, m_file_t fp)
 {
   return simcall_file_close(storage, (smx_file_t)fp);
 }
 
+/** \ingroup m_file_management
+ * \brief Stats the file pointed by fd
+ *
+ * \param storage is the name where find the stream
+ * \param fd is the file descriptor
+ * \param buf is the return structure with informations
+ * \return 0 on success or 1 on error
+ */
 int MSG_file_stat(const char* storage, int fd, void* buf)
 {
   return simcall_file_stat(storage, fd, buf);