From e858f7049c6407648e624cb43a1819237541fd84 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 10 Jan 2013 17:06:06 -0600 Subject: cpukit: Fix many Doxygen warnings --- cpukit/libfs/src/devfs/devfs.h | 3 +-- cpukit/libmisc/mouse/serial_mouse.h | 12 ++++++------ cpukit/rtems/include/rtems/rtems/clock.h | 10 ++++++---- cpukit/rtems/include/rtems/rtems/ratemon.h | 2 +- cpukit/rtems/include/rtems/rtems/region.h | 2 +- cpukit/rtems/include/rtems/rtems/sem.h | 2 +- cpukit/sapi/inline/rtems/timespec.inl | 17 ++++++++--------- cpukit/score/include/rtems/score/apimutex.h | 2 +- cpukit/score/include/rtems/score/chain.h | 2 +- cpukit/score/include/rtems/score/coremsg.h | 11 +++++++---- cpukit/score/include/rtems/score/isr.h | 4 ++-- cpukit/score/include/rtems/score/rbtree.h | 7 +++---- cpukit/score/include/rtems/score/thread.h | 8 +------- cpukit/score/include/rtems/score/threadq.h | 14 ++++++++++++-- cpukit/score/include/rtems/score/timespec.h | 4 ++-- cpukit/score/include/rtems/score/tod.h | 7 ++++--- cpukit/score/inline/rtems/score/rbtree.inl | 16 ++++++++-------- cpukit/score/inline/rtems/score/states.inl | 2 +- 18 files changed, 66 insertions(+), 59 deletions(-) diff --git a/cpukit/libfs/src/devfs/devfs.h b/cpukit/libfs/src/devfs/devfs.h index 850a892a36..0213e072f9 100644 --- a/cpukit/libfs/src/devfs/devfs.h +++ b/cpukit/libfs/src/devfs/devfs.h @@ -264,10 +264,9 @@ extern int devFS_initialize( */ extern void devFS_Show(void); -/** @} */ #ifdef __cplusplus } #endif - +/** @} */ #endif diff --git a/cpukit/libmisc/mouse/serial_mouse.h b/cpukit/libmisc/mouse/serial_mouse.h index e4f0ee4491..307587fd7e 100644 --- a/cpukit/libmisc/mouse/serial_mouse.h +++ b/cpukit/libmisc/mouse/serial_mouse.h @@ -49,7 +49,7 @@ extern "C" { * * @param[in] major is the mouse device major number * @param[in] minor is the mouse device minor number - * @param[in] arguments points to device driver arguments + * @param[in] arg points to device driver arguments */ rtems_device_driver serial_mouse_initialize( rtems_device_major_number major, @@ -65,7 +65,7 @@ rtems_device_driver serial_mouse_initialize( * * @param[in] major is the mouse device major number * @param[in] minor is the mouse device minor number - * @param[in] arguments points to device driver arguments + * @param[in] arg points to device driver arguments */ rtems_device_driver serial_mouse_open( rtems_device_major_number major, @@ -81,7 +81,7 @@ rtems_device_driver serial_mouse_open( * * @param[in] major is the mouse device major number * @param[in] minor is the mouse device minor number - * @param[in] arguments points to device driver arguments + * @param[in] arg points to device driver arguments */ rtems_device_driver serial_mouse_close( rtems_device_major_number major, @@ -97,7 +97,7 @@ rtems_device_driver serial_mouse_close( * * @param[in] major is the mouse device major number * @param[in] minor is the mouse device minor number - * @param[in] arguments points to device driver arguments + * @param[in] arg points to device driver arguments */ rtems_device_driver serial_mouse_read( rtems_device_major_number major, @@ -113,7 +113,7 @@ rtems_device_driver serial_mouse_read( * * @param[in] major is the mouse device major number * @param[in] minor is the mouse device minor number - * @param[in] arguments points to device driver arguments + * @param[in] arg points to device driver arguments */ rtems_device_driver serial_mouse_write( rtems_device_major_number major, @@ -129,7 +129,7 @@ rtems_device_driver serial_mouse_write( * * @param[in] major is the mouse device major number * @param[in] minor is the mouse device minor number - * @param[in] arguments points to device driver arguments + * @param[in] arg points to device driver arguments */ rtems_device_driver serial_mouse_control( rtems_device_major_number major, diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h index c5355230f9..3254b59dc1 100644 --- a/cpukit/rtems/include/rtems/rtems/clock.h +++ b/cpukit/rtems/include/rtems/rtems/clock.h @@ -230,10 +230,8 @@ rtems_status_code rtems_clock_set_nanoseconds_extension( * * @retval This method returns RTEMS_SUCCESSFUL if there was not an * error. Otherwise, a status code is returned indicating the - * source of the error. If successful, the uptime will be + * source of the error. If successful, the @a uptime will be * filled in. - * - * Clock Manager - get uptime */ rtems_status_code rtems_clock_get_uptime( struct timespec *uptime @@ -242,7 +240,11 @@ rtems_status_code rtems_clock_get_uptime( /** * @brief Gets the System Uptime in the Struct Timeval Format * - * @param[out] Returns the system uptime. Pointer must not be NULL. + * @param[out] uptime is a pointer to a struct timeval structure. + * + * @retval This methods returns the system uptime. + * + * @note Pointer must not be NULL. */ void rtems_clock_get_uptime_timeval( struct timeval *uptime ); diff --git a/cpukit/rtems/include/rtems/rtems/ratemon.h b/cpukit/rtems/include/rtems/rtems/ratemon.h index 91b84e3a26..634889aeeb 100644 --- a/cpukit/rtems/include/rtems/rtems/ratemon.h +++ b/cpukit/rtems/include/rtems/rtems/ratemon.h @@ -434,7 +434,7 @@ void rtems_rate_monotonic_report_statistics( void ); * result is set to indicate the current state of the period. * * @param[in] id is the rate monotonic id - * @param[in] lenght is the length of period (in ticks) + * @param[in] length is the length of period (in ticks) * * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful */ diff --git a/cpukit/rtems/include/rtems/rtems/region.h b/cpukit/rtems/include/rtems/rtems/region.h index 17519a5791..a99a497b8d 100644 --- a/cpukit/rtems/include/rtems/rtems/region.h +++ b/cpukit/rtems/include/rtems/rtems/region.h @@ -306,7 +306,7 @@ rtems_status_code rtems_region_return_segment( * satisfied. * * @param[in] id is the region id - * @param[in] segmet is the pointer to segment address + * @param[in] segment is the pointer to segment address * @param[in] size is the new required size * @retval RTEMS_SUCCESSFUL if operation successful, RTEMS_UNSATISFIED if the * the segment can't be resized in place or any other code at failure diff --git a/cpukit/rtems/include/rtems/rtems/sem.h b/cpukit/rtems/include/rtems/rtems/sem.h index 4442b1d68c..dafd1eac0d 100644 --- a/cpukit/rtems/include/rtems/rtems/sem.h +++ b/cpukit/rtems/include/rtems/rtems/sem.h @@ -271,7 +271,7 @@ rtems_status_code _Semaphore_Translate_core_mutex_return_code ( * This function returns a RTEMS status code based on the semaphore * status code specified. * - * @param[in] status is the semaphore status code to translate + * @param[in] the_mutex_status is the semaphore status code to translate * * @retval translated RTEMS status code */ diff --git a/cpukit/sapi/inline/rtems/timespec.inl b/cpukit/sapi/inline/rtems/timespec.inl index d8fc5f69fb..31d445c45d 100644 --- a/cpukit/sapi/inline/rtems/timespec.inl +++ b/cpukit/sapi/inline/rtems/timespec.inl @@ -52,8 +52,8 @@ RTEMS_INLINE_ROUTINE bool rtems_timespec_is_valid( * @param[in] lhs is the left hand side timespec * @param[in] rhs is the right hand side timespec * - * @retval true @a lhs is less than @a rhr. - * @retval false @a lhs is not less than @a rhr. + * @retval true @a lhs is less than @a rhs. + * @retval false @a lhs is not less than @a rhs. * */ RTEMS_INLINE_ROUTINE bool rtems_timespec_less_than( @@ -250,17 +250,16 @@ RTEMS_INLINE_ROUTINE uint32_t rtems_timespec_get_nanoseconds( return _Timespec_Get_nanoseconds( _time ); } - /** * @brief Timespec greater than operator. * * This method is the greater than operator for timespecs. * - * @param[in] lhs is the left hand side timespec - * @param[in] rhs is the right hand side timespec + * @param[in] _lhs is the left hand side timespec + * @param[in] _rhs is the right hand side timespec * - * @retval true @a lhs is greater than @a rhr. - * @retval false @a lhs is not greater than @a rhr. + * @retval true @a _lhs is greater than @a _rhs. + * @retval false @a _lhs is not greater than @a _rhs. */ RTEMS_INLINE_ROUTINE bool rtems_timespec_greater_than( const struct timespec *_lhs, @@ -277,8 +276,8 @@ RTEMS_INLINE_ROUTINE bool rtems_timespec_greater_than( * @param[in] lhs is the left hand side timespec * @param[in] rhs is the right hand side timespec * - * @retval true @a lhs is equal to @a rhr. - * @retval false @a lhs is not equal to @a rhr. + * @retval true @a lhs is equal to @a rhs. + * @retval false @a lhs is not equal to @a rhs. */ RTEMS_INLINE_ROUTINE bool rtems_timespec_equal_to( const struct timespec *lhs, diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h index a9351003fc..60c21ad29c 100644 --- a/cpukit/score/include/rtems/score/apimutex.h +++ b/cpukit/score/include/rtems/score/apimutex.h @@ -61,7 +61,7 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information; * The value @a maximum_mutexes is the maximum number of API mutexes that may * exist at any time. * - * @param[in] Maximum_mutexex is the maximum number of API mutexes. + * @param[in] maximum_mutexes is the maximum number of API mutexes. */ void _API_Mutex_Initialization( uint32_t maximum_mutexes ); diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h index ea9f95d87c..4b2a449823 100644 --- a/cpukit/score/include/rtems/score/chain.h +++ b/cpukit/score/include/rtems/score/chain.h @@ -165,7 +165,7 @@ Chain_Node *_Chain_Get( * * @param[in] after_node is the pointer to the node in chain to be * inserted after - * @param[in] node is the pointer to the node to be inserted + * @param[in] the_node is the pointer to the node to be inserted * * @note It disables interrupts to ensure the atomicity * of the insert operation. diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h index 7363060c13..d022391182 100644 --- a/cpukit/score/include/rtems/score/coremsg.h +++ b/cpukit/score/include/rtems/score/coremsg.h @@ -450,15 +450,18 @@ CORE_message_queue_Status _CORE_message_queue_Submit( * It is used when unblocking a remote thread. * @param[in] buffer is the starting address of the message buffer to * to be filled in with a message - * @param[in] size is the size of the @a buffer and indicates the maximum - * size message that the caller can receive. + * @param[in] size_p is a pointer to the size of the @a buffer and + * indicates the maximum size message that the caller can receive. * @param[in] wait indicates whether the calling thread is willing to block * if the message queue is empty. * @param[in] timeout is the maximum number of clock ticks that the calling * thread is willing to block if the message queue is empty. * - * @retval indication of the successful completion or reason for failure - * @note Returns message priority via return are in TCB. + * @retval indication of the successful completion or reason for failure. + * On success, the location pointed to @a size_p will contain the + * size of the received message. + * + * @note Returns message priority via return area in TCB. * * - INTERRUPT LATENCY: * + available diff --git a/cpukit/score/include/rtems/score/isr.h b/cpukit/score/include/rtems/score/isr.h index aecdfeea5e..58d4fbc952 100644 --- a/cpukit/score/include/rtems/score/isr.h +++ b/cpukit/score/include/rtems/score/isr.h @@ -117,7 +117,7 @@ void _ISR_Handler_initialization ( void ); * LEVEL. It is used at the end of a critical section of code to * enable interrupts so they can be processed again. * - * @param[in] level contains the interrupt level mask level + * @param[in] _level contains the interrupt level mask level * previously returned by @ref _ISR_Disable_on_this_core. */ #define _ISR_Enable_on_this_core( _level ) \ @@ -142,7 +142,7 @@ void _ISR_Handler_initialization ( void ); * must be selected with care to ensure that the critical section * properly protects itself. * - * @param[in] level contains the interrupt level mask level + * @param[in] _level contains the interrupt level mask level * previously returned by @ref _ISR_Disable_on_this_core. */ #define _ISR_Flash_on_this_core( _level ) \ diff --git a/cpukit/score/include/rtems/score/rbtree.h b/cpukit/score/include/rtems/score/rbtree.h index 7b86d29304..55b5c55720 100644 --- a/cpukit/score/include/rtems/score/rbtree.h +++ b/cpukit/score/include/rtems/score/rbtree.h @@ -262,12 +262,11 @@ RBTree_Node *_RBTree_Find( /** * @brief Find the control structure of the tree containing the given node. * - * This function returns a pointer called @a return_header to the control structure of the tree - * containing @a the_node, if it exists, and @a NULL if not. + * This function returns a pointer called @a return_header to the + * control structure of the tree containing @a the_node, if it exists, + * and @a NULL if not. * * @param[in] the_node is the pointer to the rbtree node. - * @param[out] return_header is the pointer to control header of rbtree. - * @param[out] NULL is returned if there is no control header available. * * -INTERRUPT LATENCY: * + single case diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h index f9f2317ea6..248be62c95 100644 --- a/cpukit/score/include/rtems/score/thread.h +++ b/cpukit/score/include/rtems/score/thread.h @@ -758,17 +758,11 @@ void _Thread_Load_environment( * which must be performed immediately before and after the user's * thread executes are found here. * - * NOTE: - * - * On entry, it is assumed all interrupts are blocked and that this + * @note On entry, it is assumed all interrupts are blocked and that this * routine needs to set the initial isr level. This may or may not * actually be needed by the context switch routine and as a result * interrupts may already be at there proper level. Either way, * setting the initial isr level properly here is safe. - * - * @param[in]: NONE - * - * @param[out]: NONE */ void _Thread_Handler( void ); diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h index c004d2d8ea..1be336993c 100644 --- a/cpukit/score/include/rtems/score/threadq.h +++ b/cpukit/score/include/rtems/score/threadq.h @@ -165,6 +165,12 @@ Thread_Control *_Thread_queue_First( * * This routine unblocks all threads blocked on the_thread_queue * and cancels any associated timeouts. + * + * @param[in] the_thread_queue is the pointer to a threadq header + * @param[in] remote_extract_callout points to a method to invoke to + * invoke when a remote thread is unblocked + * @param[in] status is the status which will be returned to + * all unblocked threads */ void _Thread_queue_Flush( Thread_queue_Control *the_thread_queue, @@ -180,7 +186,7 @@ void _Thread_queue_Flush( * threads which block on the_thread_queue is state. * * @param[in] the_thread_queue is the pointer to a threadq header - * @param[in] discipline is the queueing discipline + * @param[in] the_discipline is the queueing discipline * @param[in] state is the state of waiting threads * @param[in] timeout_status is the return on a timeout */ @@ -218,7 +224,11 @@ Thread_Control *_Thread_queue_Dequeue_priority( * priority discipline. * * @param[in] the_thread_queue is the pointer to threadq - * @param[in] thread is the thread to insert + * @param[in] the_thread is the thread to insert + * @param[in] level_p is a pointer to an interrupt level to be returned + * + * @retval This methods returns an indication of the blocking state as + * well as filling in *@ level_p with the previous interrupt level. * * - INTERRUPT LATENCY: * + forward less than diff --git a/cpukit/score/include/rtems/score/timespec.h b/cpukit/score/include/rtems/score/timespec.h index 99424f92dc..e72ccb2b72 100644 --- a/cpukit/score/include/rtems/score/timespec.h +++ b/cpukit/score/include/rtems/score/timespec.h @@ -123,8 +123,8 @@ bool _Timespec_Less_than( * * This method is the greater than operator for timespecs. * - * @param[in] lhs is the left hand side timespec - * @param[in] rhs is the right hand side timespec + * @param[in] _lhs is the left hand side timespec + * @param[in] _rhs is the right hand side timespec * * @retval This method returns true if @a lhs is greater than the @a rhs and * false otherwise. diff --git a/cpukit/score/include/rtems/score/tod.h b/cpukit/score/include/rtems/score/tod.h index cfbd00ba52..df73f95970 100644 --- a/cpukit/score/include/rtems/score/tod.h +++ b/cpukit/score/include/rtems/score/tod.h @@ -205,10 +205,11 @@ static inline void _TOD_Set( * * This function invokes the nanoseconds extension. * - * @param[out] snapshot The snapshot. - * @param[in] source The clock. + * @param[out] snapshot points to an area that will contain the current + * TOD plus the BSP nanoseconds since last tick adjustment + * @param[in] clock contains the current TOD * - * @retval The snapshot. + * @retval @a snapshot */ Timestamp_Control *_TOD_Get_with_nanoseconds( Timestamp_Control *snapshot, diff --git a/cpukit/score/inline/rtems/score/rbtree.inl b/cpukit/score/inline/rtems/score/rbtree.inl index 7bbb9c6af0..8b4234de57 100644 --- a/cpukit/score/inline/rtems/score/rbtree.inl +++ b/cpukit/score/inline/rtems/score/rbtree.inl @@ -65,7 +65,9 @@ RTEMS_INLINE_ROUTINE bool _RBTree_Is_node_off_rbtree( const RBTree_Node *node ) { - return (node->parent == NULL) && (node->child[RBT_LEFT] == NULL) && (node->child[RBT_RIGHT] == NULL); + return (node->parent == NULL) && + (node->child[RBT_LEFT] == NULL) && + (node->child[RBT_RIGHT] == NULL); } /** @@ -255,7 +257,8 @@ RTEMS_INLINE_ROUTINE bool _RBTree_Has_only_one_node( ) { if(!the_rbtree) return false; /* TODO: expected behavior? */ - return (the_rbtree->root->child[RBT_LEFT] == NULL && the_rbtree->root->child[RBT_RIGHT] == NULL); + return (the_rbtree->root->child[RBT_LEFT] == NULL && + the_rbtree->root->child[RBT_RIGHT] == NULL); } /** @@ -385,11 +388,10 @@ RTEMS_INLINE_ROUTINE bool _RBTree_Is_lesser( /** * @brief Returns the predecessor of a node. * - * @param[in] rbtree is the red-black tree. * @param[in] node is the node. * - * @retval NULL The predecessor does not exist. - * @retval otherwise The predecessor node. + * @retval NULL The predecessor does not exist. Otherwise it returns + * the predecessor node. */ RTEMS_INLINE_ROUTINE RBTree_Node *_RBTree_Predecessor_unprotected( const RBTree_Node *node @@ -413,11 +415,9 @@ RTEMS_INLINE_ROUTINE RBTree_Node *_RBTree_Predecessor( /** * @brief Returns the successor of a node. * - * @param[in] rbtree is the red-black tree. * @param[in] node is the node. * - * @retval NULL The successor does not exist. - * @retval otherwise The successor node. + * @retval NULL The successor does not exist. Otherwise the successor node. */ RTEMS_INLINE_ROUTINE RBTree_Node *_RBTree_Successor_unprotected( const RBTree_Node *node diff --git a/cpukit/score/inline/rtems/score/states.inl b/cpukit/score/inline/rtems/score/states.inl index 8d335c9475..5dfdc4230a 100644 --- a/cpukit/score/inline/rtems/score/states.inl +++ b/cpukit/score/inline/rtems/score/states.inl @@ -51,7 +51,7 @@ RTEMS_INLINE_ROUTINE States_Control _States_Set ( * This function clears the given states_to_clear into the current_state * passed in. The result is returned to the user in current_state. * - * @param[in] states_to_set is the state bits to clean + * @param[in] states_to_clear is the state bits to clean * @param[in] current_state is the state set to remove them from * * @return This method returns the updated states value. -- cgit v1.2.3