[rtems commit] cpukit: Fix many Doxygen warnings
Joel Sherrill
joel at rtems.org
Thu Jan 10 23:02:06 UTC 2013
Module: rtems
Branch: master
Commit: e858f7049c6407648e624cb43a1819237541fd84
Changeset: http://git.rtems.org/rtems/commit/?id=e858f7049c6407648e624cb43a1819237541fd84
Author: Joel Sherrill <joel.sherrill at oarcorp.com>
Date: Thu Jan 10 17:06:06 2013 -0600
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 850a892..0213e07 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 e4f0ee4..307587f 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 c535523..3254b59 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 91b84e3..634889a 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 17519a5..a99a497 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 4442b1d..dafd1ea 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 d8fc5f6..31d445c 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 a935100..60c21ad 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 ea9f95d..4b2a449 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 7363060..d022391 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 aecdfee..58d4fbc 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 7b86d29..55b5c55 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 f9f2317..248be62 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 c004d2d..1be3369 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 99424f9..e72ccb2 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 cfbd00b..df73f95 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 7bbb9c6..8b4234d 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 8d335c9..5dfdc42 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.
More information about the vc
mailing list