rtems: Add files to Doxygen groups

Provide basic Doxygen comments.

Update #3706.
Update #3707.

5 files changed, 141 insertions, 32 deletions

diff --git a/cpukit/include/rtems/linkersets.h b/cpukit/include/rtems/linkersets.h
index ef1b0d38d4..a5d7b1b037 100644
--- a/cpukit/include/rtems/linkersets.h
+++ b/cpukit/include/rtems/linkersets.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPILinkerSets
+ *
+ * @brief This header file provides the linker sets API.
+ */
+
 /*
  * Copyright (C) 2015, 2020 embedded brains GmbH & Co. KG
  *
@@ -34,6 +42,36 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @ingroup RTEMSImpl
+ *
+ * @brief Obfuscates a pointer to prevent compiler optimizations.
+ *
+ * @param ptr is the pointer to obfuscate.
+ *
+ * @return Returns the unsigned integer representation of the obfuscated
+ *   pointer.
+ */
+static inline uintptr_t _Linker_set_Obfuscate( const void *ptr )
+{
+  uintptr_t addr;
+
+  addr = (uintptr_t) ptr;
+  RTEMS_OBFUSCATE_VARIABLE( addr );
+
+  return addr;
+}
+
+/**
+ * @defgroup RTEMSAPILinkerSets Linker Sets
+ *
+ * @ingroup RTEMSAPI
+ *
+ * @brief This group contains the linker sets API.
+ *
+ * @{
+ */
+
 #define RTEMS_LINKER_SET_BEGIN( set ) \
   _Linker_set_##set##_begin
 
@@ -129,16 +167,6 @@ extern "C" {
   decl \
   RTEMS_SECTION( ".rtemsrwset." #set ".content" )
 
-static inline uintptr_t _Linker_set_Obfuscate( const void *ptr )
-{
-  uintptr_t addr;
-
-  addr = (uintptr_t) ptr;
-  RTEMS_OBFUSCATE_VARIABLE( addr );
-
-  return addr;
-}
-
 #define RTEMS_LINKER_SET_SIZE( set ) \
   ( _Linker_set_Obfuscate( RTEMS_LINKER_SET_END( set ) ) \
     - _Linker_set_Obfuscate( RTEMS_LINKER_SET_BEGIN( set ) ) )
@@ -157,6 +185,8 @@ static inline uintptr_t _Linker_set_Obfuscate( const void *ptr )
     ++item \
   )
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/cpukit/include/rtems/sysinit.h b/cpukit/include/rtems/sysinit.h
index b973ecfc91..3e6f4d9933 100644
--- a/cpukit/include/rtems/sysinit.h
+++ b/cpukit/include/rtems/sysinit.h
@@ -1,7 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPISystemInit
+ *
+ * @brief This header file provides the API of the @ref RTEMSAPISystemInit.
+ */
+
 /*
- * Copyright (C) 2015, 2020 embedded brains GmbH & Co. KG
+ * Copyright (C) 2015, 2023 embedded brains GmbH & Co. KG
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -34,6 +42,54 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @ingroup RTEMSImpl
+ *
+ * @brief Enables a verbose system initialization.
+ */
+void _Sysinit_Verbose( void );
+
+/**
+ * @ingroup RTEMSImpl
+ *
+ * @brief Creates the system initialization item associated with the handler
+ *   and index.
+ *
+ * The enum helps to detect typos in the module and order parameters of
+ * RTEMS_SYSINIT_ITEM().
+ */
+#define _RTEMS_SYSINIT_INDEX_ITEM( handler, index ) \
+  enum { _Sysinit_##handler = index }; \
+  RTEMS_LINKER_ROSET_ITEM_ORDERED( \
+    _Sysinit, \
+    rtems_sysinit_item, \
+    handler, \
+    index \
+  ) = { handler }
+
+/**
+ * @ingroup RTEMSImpl
+ *
+ * @brief Creates the system initialization item associated with the handler,
+ *   module, and order.
+ *
+ * This helper macro is used to perform parameter expansion in
+ * RTEMS_SYSINIT_ITEM().
+ */
+#define _RTEMS_SYSINIT_ITEM( handler, module, order ) \
+  _RTEMS_SYSINIT_INDEX_ITEM( handler, 0x##module##order )
+
+/**
+ * @defgroup RTEMSAPISystemInit System Initialization Support
+ *
+ * @ingroup RTEMSAPI
+ *
+ * @brief The system initialization support provides an ordered invocation of
+ *   system initialization handlers registered in a linker set.
+ *
+ * @{
+ */
+
 /*
  * The value of each module define must consist of exactly six hexadecimal
  * digits without a 0x-prefix.  A 0x-prefix is concatenated with the module and
@@ -133,29 +189,22 @@ typedef struct {
   rtems_sysinit_handler handler;
 } rtems_sysinit_item;
 
-/* The enum helps to detect typos in the module and order parameters */
-#define _RTEMS_SYSINIT_INDEX_ITEM( handler, index ) \
-  enum { _Sysinit_##handler = index }; \
-  RTEMS_LINKER_ROSET_ITEM_ORDERED( \
-    _Sysinit, \
-    rtems_sysinit_item, \
-    handler, \
-    index \
-  ) = { handler }
-
-/* Create index from module and order */
-#define _RTEMS_SYSINIT_ITEM( handler, module, order ) \
-  _RTEMS_SYSINIT_INDEX_ITEM( handler, 0x##module##order )
-
-/* Perform parameter expansion */
+/**
+ * @brief Creates the system initialization item associated with the handler,
+ *   module, and order.
+ *
+ * @param handler is the system initialization handler.
+ *
+ * @param module is the system initialization module.  It shall be a 6-digit
+ *   hex number without a 0x-prefix.
+ *
+ * @param order is the system initialization order with respect to the module.
+ *   It shall be a 2-digit hex number without a 0x-prefix.
+ */
 #define RTEMS_SYSINIT_ITEM( handler, module, order ) \
   _RTEMS_SYSINIT_ITEM( handler, module, order )
 
-/**
- * @brief System initialization handler to enable a verbose system
- * initialization.
- */
-void _Sysinit_Verbose( void );
+/** @} */
 
 #ifdef __cplusplus
 }
diff --git a/cpukit/include/rtems/thread.h b/cpukit/include/rtems/thread.h
index 739744b4e0..c3d7de67f4 100644
--- a/cpukit/include/rtems/thread.h
+++ b/cpukit/include/rtems/thread.h
@@ -1,5 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPISelfContainedObjects
+ *
+ * @brief This header file provides the API of
+ *   @ref RTEMSAPISelfContainedObjects.
+ */
+
 /*
  * Copyright (c) 2017 embedded brains GmbH & Co. KG
  *
@@ -45,6 +54,16 @@ void _Semaphore_Post_binary(struct _Semaphore_Control *);
 
 typedef struct _Mutex_Control rtems_mutex;
 
+/**
+ * @defgroup RTEMSAPISelfContainedObjects Self-Contained Objects
+ *
+ * @ingroup RTEMSAPI
+ *
+ * @brief This group contains the self-contained objects API.
+ *
+ * @{
+ */
+
 #define RTEMS_MUTEX_INITIALIZER( name ) _MUTEX_NAMED_INITIALIZER( name )
 
 static __inline void rtems_mutex_init( rtems_mutex *mutex, const char *name )
@@ -309,6 +328,8 @@ static __inline void rtems_binary_semaphore_destroy(
   _Semaphore_Destroy( &binary_semaphore->Semaphore );
 }
 
+/** @} */
+
 __END_DECLS
 
 #endif /* _RTEMS_THREAD_H */
diff --git a/cpukit/sapi/src/cpucounterconverter.c b/cpukit/sapi/src/cpucounterconverter.c
index 4cabdc5e4a..587fe460df 100644
--- a/cpukit/sapi/src/cpucounterconverter.c
+++ b/cpukit/sapi/src/cpucounterconverter.c
@@ -1,5 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup RTEMSImpl
+ *
+ * @brief This source file contains a implementation of the counter value
+ *   conversion functions.
+ */
+
 /*
  * Copyright (C) 2014, 2018 embedded brains GmbH & Co. KG
  *
diff --git a/cpukit/sapi/src/version.c b/cpukit/sapi/src/version.c
index 385cf83f2a..ea07683876 100644
--- a/cpukit/sapi/src/version.c
+++ b/cpukit/sapi/src/version.c
@@ -3,7 +3,7 @@
 /**
  * @file
  *
- * @ingroup RTEMSAPIClassicVersion
+ * @ingroup RTEMSImplClassic
  *
  * @brief This source file contains the implementation of rtems_version(),
  *   rtems_version_control_key(), rtems_version_major(), rtems_version_minor(),