From fbe8a7ab90165ebfd9f3fab166cefe74e4e6de6d Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 3 Apr 2019 12:44:42 +0200 Subject: doxygen: Rework some Doxygen comments 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(-) (limited to 'cpukit/include') 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. -- cgit v1.2.3