[PATCH v2] doxygen: Rework some Doxygen comments

[Sebastian Huber]

They are intended as examples in the RTEMS Software Engineering manual.

Update #3704.
---
 cpukit/include/rtems/rtems/message.h | 74 ++++++++++++++++++++----------------
 cpukit/include/rtems/score/rbtree.h  |  4 +-
 cpukit/include/rtems/score/wkspace.h | 17 ++++-----
 3 files changed, 51 insertions(+), 44 deletions(-)

diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h
index d224c95d80..675cd98acc 100644
--- a/cpukit/include/rtems/rtems/message.h
+++ b/cpukit/include/rtems/rtems/message.h
@@ -104,19 +104,27 @@ rtems_status_code rtems_message_queue_delete(
 );
 
 /**
- *  @brief rtems_message_queue_send
- *
- *  Message Queue Manager - rtems_message_queue_send
- *
- *  This routine implements the rtems_message_queue_send directive.
- *  This directive sends the message buffer to the message queue
- *  indicated by ID.  If one or more tasks is blocked waiting
- *  to receive a message from this message queue, then one will
- *  receive the message.  The task selected to receive the
- *  message is based on the task queue discipline algorithm in
- *  use by this particular message queue.  If no tasks are waiting,
- *  then the message buffer will be placed at the REAR of the
- *  chain of pending messages for this message queue.
+ * @brief Sends a message to the message queue.
+ *
+ * This directive sends the message buffer to the message queue indicated by
+ * ID.  If one or more tasks is blocked waiting to receive a message from this
+ * message queue, then one will receive the message.  The task selected to
+ * receive the message is based on the task queue discipline algorithm in use
+ * by this particular message queue.  If no tasks are waiting, then the message
+ * buffer will be placed at the rear of the chain of pending messages for this
+ * message queue.
+ *
+ * @param id The message queue ID.
+ * @param buffer The message content buffer.
+ * @param size The size of the message.
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_ID Invalid message queue ID.
+ * @retval RTEMS_INVALID_ADDRESS The message buffer pointer is @c NULL.
+ * @retval RTEMS_INVALID_SIZE The message size is larger than the maximum
+ *   message size of the message queue.
+ * @retval RTEMS_TOO_MANY The new message would exceed the message queue limit
+ *   for pending messages.
  */
 rtems_status_code rtems_message_queue_send(
   rtems_id    id,
@@ -169,25 +177,27 @@ rtems_status_code rtems_message_queue_broadcast(
 );
 
 /**
- * @brief RTEMS Message Queue Receive
- *
- * This routine implements the rtems_message_queue_receive directive.
- * This directive is invoked when the calling task wishes to receive
- * a message from the message queue indicated by ID. The received
- * message is to be placed in buffer. If no messages are outstanding
- * and the option_set indicates that the task is willing to block,
- * then the task will be blocked until a message arrives or until,
- * optionally, timeout clock ticks have passed.
- *
- * @param[in] id is the queue id
- * @param[in] buffer is the pointer to message buffer
- * @param[in] size is the size of message receive
- * @param[in] option_set is the options on receive
- * @param[in] timeout is the number of ticks to wait
- *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
+ * @brief Receives a message from the message queue
+ *
+ * This directive is invoked when the calling task wishes to receive a message
+ * from the message queue indicated by ID. The received message is to be placed
+ * in the buffer. If no messages are outstanding and the option set indicates
+ * that the task is willing to block, then the task will be blocked until a
+ * message arrives or until, optionally, timeout clock ticks have passed.
+ *
+ * @param id The message queue ID.
+ * @param[out] buffer The buffer for the message content.  The buffer must be
+ *   large enough to store maximum size messages of this message queue.
+ * @param[out] size The size of the message.
+ * @param option_set The option set, e.g. RTEMS_NO_WAIT or RTEMS_WAIT.
+ * @param timeout The number of ticks to wait if the RTEMS_WAIT is set.  Use
+ *   RTEMS_NO_TIMEOUT to wait indefinitely.
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_ID Invalid message queue ID.
+ * @retval RTEMS_INVALID_ADDRESS The message buffer pointer or the message size
+ *   pointer is @c NULL.
+ * @retval RTEMS_TIMEOUT A timeout occurred and no message was received.
  */
 rtems_status_code rtems_message_queue_receive(
   rtems_id        id,
diff --git a/cpukit/include/rtems/score/rbtree.h b/cpukit/include/rtems/score/rbtree.h
index 51f9125dda..c01a893b6e 100644
--- a/cpukit/include/rtems/score/rbtree.h
+++ b/cpukit/include/rtems/score/rbtree.h
@@ -106,8 +106,8 @@ RTEMS_INLINE_ROUTINE bool _RBTree_Is_node_off_tree(
 /**
  * @brief Rebalances the red-black tree after insertion of the node.
  *
- * @param[in] the_rbtree The red-black tree control.
- * @param[in] the_node The most recently inserted node.
+ * @param[in, out] the_rbtree The red-black tree control.
+ * @param[in, out] the_node The most recently inserted node.
  */
 void _RBTree_Insert_color(
   RBTree_Control *the_rbtree,
diff --git a/cpukit/include/rtems/score/wkspace.h b/cpukit/include/rtems/score/wkspace.h
index cbb4011824..551a10d50d 100644
--- a/cpukit/include/rtems/score/wkspace.h
+++ b/cpukit/include/rtems/score/wkspace.h
@@ -57,19 +57,16 @@ void _Workspace_Handler_initialization(
 );
 
 /**
- * @brief Allocate memory from workspace.
+ * @brief Allocates a memory block of the specified size from the workspace.
  *
- *  This routine returns the address of a block of memory of size
- *  bytes.  If a block of the appropriate size cannot be allocated
- *  from the workspace, then NULL is returned.
- *
- *  @param size is the requested size
+ * @param size The size of the memory block.
  *
- *  @retval a pointer to the requested memory or NULL.
+ * @retval pointer The pointer to the memory block.  The pointer is at least
+ *   aligned by CPU_HEAP_ALIGNMENT.
+ * @retval NULL No memory block with the requested size is available in the
+ *   workspace.
  */
-void *_Workspace_Allocate(
-  size_t   size
-);
+void *_Workspace_Allocate( size_t size );
 
 /**
  * @brief Allocate aligned memory from workspace.
-- 
2.16.4