Documentation improvements, renamed some event APIs.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2179 35acf78f-673a-0410-8e92-d51de3d6d3f4

1 files changed, 23 insertions, 21 deletions

diff --git a/os/kernel/src/chmboxes.c b/os/kernel/src/chmboxes.c
index 717246b88..279778e48 100644
--- a/os/kernel/src/chmboxes.c
+++ b/os/kernel/src/chmboxes.c
@@ -43,17 +43,19 @@
  *          possible approach is to allocate memory (from a memory pool as

  *          example) from the posting side and free it on the fetching side.

  *          Another approach is to set a "done" flag into the structure pointed

- *          by the message.<br>

- *          In order to use the mailboxes APIs the @p CH_USE_MAILBOXES option

+ *          by the message.

+ * @pre     In order to use the mailboxes APIs the @p CH_USE_MAILBOXES option

  *          must be enabled in @p chconf.h.

  * @{

  */

 

 #include "ch.h"

 

-#if CH_USE_MAILBOXES

+#if CH_USE_MAILBOXES || defined(__DOXYGEN__)

 /**

  * @brief   Initializes a Mailbox object.

+ * @note    This function can be invoked before the kernel is initialized

+ *          because it just prepares a @p Mailbox structure.

  *

  * @param[out] mbp      the pointer to the Mailbox structure to be initialized

  * @param[in] buf       the circular messages buffer

@@ -101,9 +103,9 @@ void chMBReset(Mailbox *mbp) {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The operation status.

- * @retval RDY_OK       if the message was correctly posted.

- * @retval RDY_RESET    if the mailbox was reset while waiting.

- * @retval RDY_TIMEOUT  if the operation timed out.

+ * @retval RDY_OK       if a message has been correctly posted.

+ * @retval RDY_RESET    if the mailbox has been reset while waiting.

+ * @retval RDY_TIMEOUT  if the operation has timed out.

  */

 msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {

   msg_t rdymsg;

@@ -127,9 +129,9 @@ msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The operation status.

- * @retval RDY_OK       if the message was correctly posted.

- * @retval RDY_RESET    if the mailbox was reset while waiting.

- * @retval RDY_TIMEOUT  if the operation timed out.

+ * @retval RDY_OK       if a message has been correctly posted.

+ * @retval RDY_RESET    if the mailbox has been reset while waiting.

+ * @retval RDY_TIMEOUT  if the operation has timed out.

  */

 msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {

   msg_t rdymsg;

@@ -160,9 +162,9 @@ msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The operation status.

- * @retval RDY_OK       if the message was correctly posted.

- * @retval RDY_RESET    if the mailbox was reset while waiting.

- * @retval RDY_TIMEOUT  if the operation timed out.

+ * @retval RDY_OK       if a message has been correctly posted.

+ * @retval RDY_RESET    if the mailbox has been reset while waiting.

+ * @retval RDY_TIMEOUT  if the operation has timed out.

  */

 msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {

   msg_t rdymsg;

@@ -186,9 +188,9 @@ msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The operation status.

- * @retval RDY_OK       if the message was correctly posted.

- * @retval RDY_RESET    if the mailbox was reset while waiting.

- * @retval RDY_TIMEOUT  if the operation timed out.

+ * @retval RDY_OK       if a message has been correctly posted.

+ * @retval RDY_RESET    if the mailbox has been reset while waiting.

+ * @retval RDY_TIMEOUT  if the operation has timed out.

  */

 msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {

   msg_t rdymsg;

@@ -219,9 +221,9 @@ msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The operation status.

- * @retval RDY_OK       if a message was correctly fetched.

- * @retval RDY_RESET    if the mailbox was reset while waiting.

- * @retval RDY_TIMEOUT  if the operation timed out.

+ * @retval RDY_OK       if a message has been correctly fetched.

+ * @retval RDY_RESET    if the mailbox has been reset while waiting.

+ * @retval RDY_TIMEOUT  if the operation has timed out.

  */

 msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {

   msg_t rdymsg;

@@ -245,9 +247,9 @@ msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The operation status.

- * @retval RDY_OK       if a message was correctly fetched.

- * @retval RDY_RESET    if the mailbox was reset while waiting.

- * @retval RDY_TIMEOUT  if the operation timed out.

+ * @retval RDY_OK       if a message has been correctly fetched.

+ * @retval RDY_RESET    if the mailbox has been reset while waiting.

+ * @retval RDY_TIMEOUT  if the operation has timed out.

  */

 msg_t chMBFetchS(Mailbox *mbp, msg_t *msgp, systime_t time) {

   msg_t rdymsg;