From 10cf427e20858a7365e1c28b693b93876f69026a Mon Sep 17 00:00:00 2001
From: schnorr <Lucas.Schnorr@imag.fr>
Date: Fri, 23 Mar 2012 14:57:31 +0100
Subject: [PATCH] improve documentation of the MSG_task_listen* functions

---
 src/msg/msg_gos.c | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/src/msg/msg_gos.c b/src/msg/msg_gos.c
index 5008fd6f92..2ad4301a7e 100644
--- a/src/msg/msg_gos.c
+++ b/src/msg/msg_gos.c
@@ -834,10 +834,11 @@ MSG_task_send_with_timeout(m_task_t task, const char *alias,
 }
 
 /** \ingroup msg_gos_functions
- * \brief Look if there is a communication on a mailbox
+ * \brief Check if there is a communication going on in a mailbox.
  *
- * \param alias the mailbox to listen
- * \return return 1 if there is a communication or 0
+ * \param alias the name of the mailbox to be considered
+ *
+ * \return Returns 1 if there is a communication, 0 otherwise
  */
 int MSG_task_listen(const char *alias)
 {
@@ -847,12 +848,14 @@ int MSG_task_listen(const char *alias)
 }
 
 /** \ingroup msg_gos_functions
- * \brief Look if there is a communication on a mailbox from
- * a given host
+ * \brief Check the number of communication actions of a given host pending in a mailbox.
  *
- * \param alias the mailbox to listen
+ * \param alias the name of the mailbox to be considered
  * \param host the host to check for communication
- * \return return 1 if there is a communication or 0
+ *
+ * \return Returns the number of pending communication actions of the host in the
+ * given mailbox, 0 if there is no pending communication actions.
+ *
  */
 int MSG_task_listen_from_host(const char *alias, m_host_t host)
 {
@@ -865,10 +868,12 @@ int MSG_task_listen_from_host(const char *alias, m_host_t host)
 
 /** \ingroup msg_gos_functions
  * \brief Look if there is a communication on a mailbox and return the
- * PID from sender process
+ * PID of the sender process.
+ *
+ * \param alias the name of the mailbox to be considered
  *
- * \param alias the mailbox to listen
- * \return return the PID of process(or 0 in case of problem)
+ * \return Returns the PID of sender process,
+ * -1 if there is no communication in the mailbox.
  */
 int MSG_task_listen_from(const char *alias)
 {
-- 
2.20.1