[PATCH 11/98] doxygen: score: adjust doc in corebarrierimpl.h to doxygen guidelines

[Sebastian Huber]

From: Andreas Dachsberger <andreas.dachsberger at embedded-brains.de>

---
 cpukit/include/rtems/score/corebarrierimpl.h | 89 ++++++++++++++++++++--------
 1 file changed, 65 insertions(+), 24 deletions(-)

diff --git a/cpukit/include/rtems/score/corebarrierimpl.h b/cpukit/include/rtems/score/corebarrierimpl.h
index 48061e6fe8..9e9ddfd81e 100644
--- a/cpukit/include/rtems/score/corebarrierimpl.h
+++ b/cpukit/include/rtems/score/corebarrierimpl.h
@@ -1,6 +1,8 @@
 /**
  * @file
  *
+ * @ingroup RTEMSScoreBarrier
+ *
  * @brief Inlined Routines Associated with the SuperCore Barrier
  *
  * This include file contains all of the inlined routines associated
@@ -29,24 +31,32 @@ extern "C" {
 
 /**
  * @addtogroup RTEMSScoreBarrier
+ *
+ * @{
  */
-/**@{**/
 
 #define CORE_BARRIER_TQ_OPERATIONS &_Thread_queue_Operations_FIFO
 
 /**
- *  @brief Initialize core barrier.
+ *  @brief Initializes the core barrier.
  *
  *  This routine initializes the barrier based on the parameters passed.
  *
- *  @param[in] the_barrier is the barrier to initialize
- *  @param[in] the_barrier_attributes define the behavior of this instance
+ *  @param[out] the_barrier The barrier to initialize.
+ *  @param[out] the_barrier_attributes The attributes which define the behavior of this instance.
  */
 void _CORE_barrier_Initialize(
   CORE_barrier_Control       *the_barrier,
   CORE_barrier_Attributes    *the_barrier_attributes
 );
 
+/**
+ * @brief Destroys the core barrier.
+ *
+ * This routine destroys the barrier.
+ *
+ * @param[out] the_barrier The barrier to destroy.
+ */
 RTEMS_INLINE_ROUTINE void _CORE_barrier_Destroy(
   CORE_barrier_Control *the_barrier
 )
@@ -54,6 +64,12 @@ RTEMS_INLINE_ROUTINE void _CORE_barrier_Destroy(
   _Thread_queue_Destroy( &the_barrier->Wait_queue );
 }
 
+/**
+ * @brief Acquires critical core barrier.
+ *
+ * @param[in, out] the_barrier The barrier to acquire.
+ * @param queue_context The thread queue context.
+ */
 RTEMS_INLINE_ROUTINE void _CORE_barrier_Acquire_critical(
   CORE_barrier_Control *the_barrier,
   Thread_queue_Context *queue_context
@@ -62,6 +78,12 @@ RTEMS_INLINE_ROUTINE void _CORE_barrier_Acquire_critical(
   _Thread_queue_Acquire_critical( &the_barrier->Wait_queue, queue_context );
 }
 
+/**
+ * @brief Releases core barrier.
+ *
+ * @param[in, out] the_barrier The barrier to release.
+ * @param queue_context The thread queue context.
+ */
 RTEMS_INLINE_ROUTINE void _CORE_barrier_Release(
   CORE_barrier_Control *the_barrier,
   Thread_queue_Context *queue_context
@@ -71,16 +93,17 @@ RTEMS_INLINE_ROUTINE void _CORE_barrier_Release(
 }
 
 /**
- *  @brief Wait for the barrier.
+ * @brief Waits for the barrier.
  *
- *  This routine wait for the barrier to be released.  If the barrier
- *  is set to automatic and this is the appropriate thread, then it returns
- *  immediately.  Otherwise, the calling thread is blocked until the barrier
- *  is released.
+ * This routine waits for the barrier to be released.  If the barrier
+ * is set to automatic and this is the appropriate thread, then it returns
+ * immediately.  Otherwise, the calling thread is blocked until the barrier
+ * is released.
  *
- *  @param[in] the_barrier is the barrier to wait for
- *  @param[in,out] executing The currently executing thread.
- *  @param[in] wait is true if the calling thread is willing to wait
+ * @param[in, out] the_barrier The barrier to wait for.
+ * @param[in, out] executing The currently executing thread.
+ * @param wait This parameter is true if the calling thread is willing to wait.
+ * @param queue_context The thread queue context.
  *
  * @return The method status.
  */
@@ -91,6 +114,13 @@ Status_Control _CORE_barrier_Seize(
   Thread_queue_Context *queue_context
 );
 
+/**
+ * @brief Flushes the barrier.
+ *
+ * @param[in, out] the_barrier The barrier to flush.
+ * @param[out] filter The filter for flushing.
+ * @param[out] queue_context The thread queue context.
+ */
 uint32_t _CORE_barrier_Do_flush(
   CORE_barrier_Control      *the_barrier,
   Thread_queue_Flush_filter  filter,
@@ -98,16 +128,15 @@ uint32_t _CORE_barrier_Do_flush(
 );
 
 /**
- *  @brief Manually release the barrier.
+ * @brief Manually releases the barrier.
  *
- *  This routine manually releases the barrier.  All of the threads waiting
- *  for the barrier will be readied.
+ * This routine manually releases the barrier.  All of the threads waiting
+ * for the barrier will be readied.
  *
- *  @param[in] the_barrier is the barrier to surrender
- *  @param[in] mp_callout is the routine to invoke if the
- *         thread unblocked is remote
+ * @param[in, out] the_barrier The barrier to surrender.
+ * @param[out] queue_context The thread queue context.
  *
- *  @retval the number of unblocked threads
+ * @return The number of unblocked threads.
  */
 RTEMS_INLINE_ROUTINE uint32_t _CORE_barrier_Surrender(
   CORE_barrier_Control *the_barrier,
@@ -121,6 +150,12 @@ RTEMS_INLINE_ROUTINE uint32_t _CORE_barrier_Surrender(
   );
 }
 
+/**
+ * @brief Flushes the barrier using _CORE_barrier_Do_flush().
+ *
+ * @param[in, out] the_barrier The barrier to flush.
+ * @param queue_context The thread queue context.
+ */
 RTEMS_INLINE_ROUTINE void _CORE_barrier_Flush(
   CORE_barrier_Control *the_barrier,
   Thread_queue_Context *queue_context
@@ -134,12 +169,15 @@ RTEMS_INLINE_ROUTINE void _CORE_barrier_Flush(
 }
 
 /**
+ * @brief Checks if the barrier is automatic.
+ *
  * This function returns true if the automatic release attribute is
  * enabled in the @a attribute_set and false otherwise.
  *
- * @param[in] the_attribute is the attribute set to test
+ * @param the_attribute The attribute set to test.
  *
- * @return true if the priority attribute is enabled
+ * @retval true The automatic release attribute is enabled.
+ * @retval false The automatic release attribute is not enabled.
  */
 RTEMS_INLINE_ROUTINE bool _CORE_barrier_Is_automatic(
   CORE_barrier_Attributes *the_attribute
@@ -150,11 +188,14 @@ RTEMS_INLINE_ROUTINE bool _CORE_barrier_Is_automatic(
 }
 
 /**
+ * @brief Returns the number of currently waiting threads.
+ *
  * This routine returns the number of threads currently waiting at the barrier.
  *
- * @param[in] the_barrier is the barrier to obtain the number of blocked
- *            threads for
- * @return the current count of this barrier
+ * @param[in] the_barrier The barrier to obtain the number of blocked
+ *            threads of.
+ *
+ * @return the current count of waiting threads of this barrier.
  */
 RTEMS_INLINE_ROUTINE uint32_t  _CORE_barrier_Get_number_of_waiting_threads(
   CORE_barrier_Control  *the_barrier
-- 
2.16.4