doxygen: score: adjust doc in userextimpl.h to doxygen guidelines

Update #3706.

1 files changed, 152 insertions, 4 deletions

diff --git a/cpukit/include/rtems/score/userextimpl.h b/cpukit/include/rtems/score/userextimpl.h
index 851e28c179..8b456c072d 100644
--- a/cpukit/include/rtems/score/userextimpl.h
+++ b/cpukit/include/rtems/score/userextimpl.h
@@ -30,8 +30,9 @@ extern "C" {
 
 /**
  * @addtogroup RTEMSScoreUserExt
+ *
+ * @{
  */
-/** @{ **/
 
 /**
  * @brief Chain iterator for dynamic user extensions.
@@ -77,15 +78,29 @@ extern Chain_Control _User_extensions_Switches_list;
 
 /**
  * @name Extension Maintainance
+ *
+ * @{
  */
-/** @{ **/
 
+/**
+ * @brief Initializes the user extensions handler.
+ */
 void _User_extensions_Handler_initialization( void );
 
+/**
+ * @brief Adds a user extension.
+ *
+ * @param extension The user extension to add.
+ */
 void _User_extensions_Add_set(
   User_extensions_Control *extension
 );
 
+/**
+ * @brief Adds a user extension.
+ *
+ * @param extension The user extension to add.
+ */
 RTEMS_INLINE_ROUTINE void _User_extensions_Add_API_set(
   User_extensions_Control *extension
 )
@@ -93,6 +108,12 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Add_API_set(
   _User_extensions_Add_set( extension );
 }
 
+/**
+ * @brief Adds a user extension with the given extension table as callouts.
+ *
+ * @param[in, out] extension The user extension to add.
+ * @param extension_table Is set as callouts for @a extension.
+ */
 RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table(
   User_extensions_Control     *extension,
   const User_extensions_Table *extension_table
@@ -103,6 +124,11 @@ RTEMS_INLINE_ROUTINE void _User_extensions_Add_set_with_table(
   _User_extensions_Add_set( extension );
 }
 
+/**
+ * @brief Removes a user extension.
+ *
+ * @param extension The user extension to remove.
+ */
 void _User_extensions_Remove_set(
   User_extensions_Control *extension
 );
@@ -125,36 +151,78 @@ typedef struct {
   bool            ok;
 } User_extensions_Thread_create_context;
 
+/**
+ * @brief Creates a visitor.
+ *
+ * @param executing The currently executing thread.
+ * @param[in, out] arg Is used as the thread create context for the operation.
+ * @param callouts The user extension table for the operation.
+ */
 void _User_extensions_Thread_create_visitor(
   Thread_Control              *executing,
   void                        *arg,
   const User_extensions_Table *callouts
 );
 
+/**
+ * @brief Deletes a visitor.
+ *
+ * @param executing The currently executing thread.
+ * @param[in, out] arg Parameter for the callout.
+ * @param callouts The user extension table for the operation.
+ */
 void _User_extensions_Thread_delete_visitor(
   Thread_Control              *executing,
   void                        *arg,
   const User_extensions_Table *callouts
 );
 
+/**
+ * @brief Starts a visitor.
+ *
+ * @param executing The currently executing thread.
+ * @param arg Parameter for the callout.
+ * @param callouts The user extension table for the operation.
+ */
 void _User_extensions_Thread_start_visitor(
   Thread_Control              *executing,
   void                        *arg,
   const User_extensions_Table *callouts
 );
 
+/**
+ * @brief Restarts a visitor.
+ *
+ * @param executing The currently executing thread.
+ * @param arg Parameter for the callout.
+ * @param callouts The user extension table for the operation.
+ */
 void _User_extensions_Thread_restart_visitor(
   Thread_Control              *executing,
   void                        *arg,
   const User_extensions_Table *callouts
 );
 
+/**
+ * @brief Calls the begin function of the thread callout for the visitor.
+ *
+ * @param executing The currently executing thread.
+ * @param arg This parameter is unused.
+ * @param callouts The user extension table for the operation.
+ */
 void _User_extensions_Thread_begin_visitor(
   Thread_Control              *executing,
   void                        *arg,
   const User_extensions_Table *callouts
 );
 
+/**
+ * @brief Calls the exitted function of the thread callout for the visitor.
+ *
+ * @param executing The currently executing thread.
+ * @param arg This parameter is unused.
+ * @param callouts The user extension table for the operation.
+ */
 void _User_extensions_Thread_exitted_visitor(
   Thread_Control              *executing,
   void                        *arg,
@@ -166,12 +234,26 @@ typedef struct {
   Internal_errors_t      error;
 } User_extensions_Fatal_context;
 
+/**
+ * @brief Calls the fatal function of the thread callout for the visitor.
+ *
+ * @param executing The currently executing thread.
+ * @param arg Is used as the user extension fatal context.
+ * @param callouts The user extension table for the operation.
+ */
 void _User_extensions_Fatal_visitor(
   Thread_Control              *executing,
   void                        *arg,
   const User_extensions_Table *callouts
 );
 
+/**
+ * @brief Terminates a visitor.
+ *
+ * @param executing The currently executing thread.
+ * @param arg This parameter is unused.
+ * @param callouts The user extension table for the operation.
+ */
 void _User_extensions_Thread_terminate_visitor(
   Thread_Control              *executing,
   void                        *arg,
@@ -182,8 +264,8 @@ void _User_extensions_Thread_terminate_visitor(
  * @brief Iterates through all user extensions and calls the visitor for each.
  *
  * @param[in, out] arg The argument passed to the visitor.
- * @param[in] visitor The visitor for each extension.
- * @param[in] direction The iteration direction for dynamic extensions.
+ * @param visitor The visitor for each extension.
+ * @param direction The iteration direction for dynamic extensions.
  */
 void _User_extensions_Iterate(
   void                     *arg,
@@ -198,6 +280,14 @@ void _User_extensions_Iterate(
  */
 /** @{ **/
 
+/**
+ * @brief Creates a thread.
+ *
+ * @param[out] created The thread to create.
+ *
+ * @retval true The operation succeeded.
+ * @retval false The operation failed.
+ */
 static inline bool _User_extensions_Thread_create( Thread_Control *created )
 {
   User_extensions_Thread_create_context ctx = { created, true };
@@ -211,6 +301,11 @@ static inline bool _User_extensions_Thread_create( Thread_Control *created )
   return ctx.ok;
 }
 
+/**
+ * @brief Deletes a thread.
+ *
+ * @param[out] created The thread to delete.
+ */
 static inline void _User_extensions_Thread_delete( Thread_Control *deleted )
 {
   _User_extensions_Iterate(
@@ -220,6 +315,11 @@ static inline void _User_extensions_Thread_delete( Thread_Control *deleted )
   );
 }
 
+/**
+ * @brief Starts a thread.
+ *
+ * @param created The thread to start.
+ */
 static inline void _User_extensions_Thread_start( Thread_Control *started )
 {
   _User_extensions_Iterate(
@@ -229,6 +329,11 @@ static inline void _User_extensions_Thread_start( Thread_Control *started )
   );
 }
 
+/**
+ * @brief Restarts a thread.
+ *
+ * @param created The thread to restart.
+ */
 static inline void _User_extensions_Thread_restart( Thread_Control *restarted )
 {
   _User_extensions_Iterate(
@@ -238,6 +343,11 @@ static inline void _User_extensions_Thread_restart( Thread_Control *restarted )
   );
 }
 
+/**
+ * @brief Begins a thread.
+ *
+ * @param created The thread to begin.
+ */
 static inline void _User_extensions_Thread_begin( Thread_Control *executing )
 {
   _User_extensions_Iterate(
@@ -247,6 +357,12 @@ static inline void _User_extensions_Thread_begin( Thread_Control *executing )
   );
 }
 
+/**
+ * @brief Switches the thread from the executing to the heir.
+ *
+ * @param executing The currently executing thread.
+ * @param heir The thread that will switch with @a executing.
+ */
 static inline void _User_extensions_Thread_switch(
   Thread_Control *executing,
   Thread_Control *heir
@@ -288,6 +404,11 @@ static inline void _User_extensions_Thread_switch(
   }
 }
 
+/**
+ * @brief A user extension thread exitted.
+ *
+ * @param created The thread.
+ */
 static inline void _User_extensions_Thread_exitted( Thread_Control *executing )
 {
   _User_extensions_Iterate(
@@ -297,6 +418,12 @@ static inline void _User_extensions_Thread_exitted( Thread_Control *executing )
   );
 }
 
+/**
+ * @brief Forwards all visitors that there was a fatal failure.
+ *
+ * @param source The error source.
+ * @param error The error.
+ */
 static inline void _User_extensions_Fatal(
   Internal_errors_Source source,
   Internal_errors_t      error
@@ -311,6 +438,11 @@ static inline void _User_extensions_Fatal(
   );
 }
 
+/**
+ * @brief Terminates the executing thread.
+ *
+ * @param executing The currently executing thread.
+ */
 static inline void _User_extensions_Thread_terminate(
   Thread_Control *executing
 )
@@ -322,6 +454,11 @@ static inline void _User_extensions_Thread_terminate(
   );
 }
 
+/**
+ * @brief Disables interrupts and acquires the lock context.
+ *
+ * @param lock_context The lock context to acquire.
+ */
 static inline void _User_extensions_Acquire( ISR_lock_Context *lock_context )
 {
   _ISR_lock_ISR_disable_and_acquire(
@@ -330,6 +467,11 @@ static inline void _User_extensions_Acquire( ISR_lock_Context *lock_context )
   );
 }
 
+/**
+ * @brief Releases the lock context and enables interrupts.
+ *
+ * @param lock_context The lock context to release.
+ */
 static inline void _User_extensions_Release( ISR_lock_Context *lock_context )
 {
   _ISR_lock_Release_and_ISR_enable(
@@ -338,6 +480,12 @@ static inline void _User_extensions_Release( ISR_lock_Context *lock_context )
   );
 }
 
+/**
+ * @brief Destroys all user extension iterators of a thread.
+ *
+ * @param[in, out] the_thread The thread to destroy all user extension
+ *      iterators of.
+ */
 static inline void _User_extensions_Destroy_iterators(
   Thread_Control *the_thread
 )