cpukit: Fix many Doxygen warnings

11 files changed, 42 insertions, 35 deletions

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.