[PATCH 11/12] sapi: Canonicalize @defgroup and @file comments

Sebastian Huber sebastian.huber at embedded-brains.de
Tue Dec 1 08:10:12 UTC 2020 

Adjust group identifier and names to be in line with a common pattern.
Use common phrases for the group and file brief descriptions.

Update #3706.
---
 cpukit/include/rtems/chain.h         | 12 ++++++++----
 cpukit/include/rtems/counter.h       |  4 ++--
 cpukit/include/rtems/extension.h     | 10 +++++-----
 cpukit/include/rtems/ioimpl.h        | 17 ++++++++++++++++-
 cpukit/include/rtems/profiling.h     |  6 +++---
 cpukit/include/rtems/rbheap.h        | 11 +++++++----
 cpukit/include/rtems/rbtree.h        | 14 ++++++--------
 cpukit/include/rtems/timecounter.h   |  9 ++++++---
 cpukit/include/rtems/version.h       |  7 +++++--
 cpukit/sapi/src/chainappendnotify.c  |  5 +++--
 cpukit/sapi/src/chaingetnotify.c     |  5 +++--
 cpukit/sapi/src/chaingetwait.c       |  5 +++--
 cpukit/sapi/src/chainprependnotify.c |  5 +++--
 cpukit/sapi/src/chainprotected.c     | 12 ++++++++++++
 cpukit/sapi/src/delaynano.c          |  9 +++++++++
 cpukit/sapi/src/delayticks.c         |  9 +++++++++
 cpukit/sapi/src/exinit.c             |  7 +++++--
 cpukit/sapi/src/exshutdown.c         |  9 +++++++++
 cpukit/sapi/src/extension.c          |  5 +++--
 cpukit/sapi/src/extensioncreate.c    |  6 ++++--
 cpukit/sapi/src/extensiondelete.c    |  5 +++--
 cpukit/sapi/src/extensionident.c     |  3 ++-
 cpukit/sapi/src/fatal.c              |  6 +++---
 cpukit/sapi/src/fatalsrctext.c       |  5 +++--
 cpukit/sapi/src/getconfigmax.c       | 22 ++++++++++++++++++++--
 cpukit/sapi/src/getcopyrightnotice.c |  5 +++--
 cpukit/sapi/src/getversionstring.c   |  5 +++--
 cpukit/sapi/src/interrtext.c         |  5 +++--
 cpukit/sapi/src/io.c                 |  6 ++++--
 cpukit/sapi/src/ioclose.c            |  4 ++--
 cpukit/sapi/src/iocontrol.c          |  4 ++--
 cpukit/sapi/src/iodefault.c          |  6 +++---
 cpukit/sapi/src/ioinitialize.c       |  4 ++--
 cpukit/sapi/src/ioopen.c             |  6 ++----
 cpukit/sapi/src/ioread.c             |  4 ++--
 cpukit/sapi/src/ioregisterdriver.c   |  5 +++--
 cpukit/sapi/src/iounregisterdriver.c |  5 +++--
 cpukit/sapi/src/iowrite.c            |  4 ++--
 cpukit/sapi/src/panic.c              |  9 +++++++++
 cpukit/sapi/src/profilingiterate.c   |  9 +++++++++
 cpukit/sapi/src/profilingreportxml.c |  9 +++++++++
 cpukit/sapi/src/rbheap.c             |  7 +++++--
 cpukit/sapi/src/rbtree.c             |  8 +++++---
 cpukit/sapi/src/rbtreefind.c         |  5 +++--
 cpukit/sapi/src/sapirbtreeinsert.c   |  9 +++++++++
 cpukit/sapi/src/sysinitverbose.c     | 13 +++++++++++--
 cpukit/sapi/src/tcsimpleinstall.c    |  9 +++++++++
 cpukit/sapi/src/version.c            | 18 +++++++++++-------
 48 files changed, 266 insertions(+), 101 deletions(-)

diff --git a/cpukit/include/rtems/chain.h b/cpukit/include/rtems/chain.h
index 25ea0b23b7..03177834a9 100644
--- a/cpukit/include/rtems/chain.h
+++ b/cpukit/include/rtems/chain.h
@@ -1,7 +1,9 @@
 /**
  * @file
  * 
- * @brief Chain API
+ * @ingroup RTEMSAPIClassicChains
+ *
+ * @brief This header file provides the Chains API.
  */
 
 /*
@@ -26,13 +28,15 @@ extern "C" {
 #endif
 
 /**
- * @defgroup ClassicChains Chains
+ * @defgroup RTEMSAPIClassicChains Chains
  *
  * @ingroup RTEMSAPIClassic
  *
- * @brief Chain API
+ * @brief The chain container provides data structures and directives to manage
+ *   user-defined data structures in doubly-linked lists.
+ *
+ * @{
  */
-/**@{**/
 
 typedef Chain_Node rtems_chain_node;
 
diff --git a/cpukit/include/rtems/counter.h b/cpukit/include/rtems/counter.h
index caf0491d9c..5bf7736e4a 100644
--- a/cpukit/include/rtems/counter.h
+++ b/cpukit/include/rtems/counter.h
@@ -30,9 +30,9 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
- * @defgroup ClassicCounter Free-Running Counter and Busy Wait Delay
+ * @defgroup RTEMSAPICounter Free-Running Counter and Busy Wait Delay
  *
- * @ingroup RTEMSAPIClassic
+ * @ingroup RTEMSAPI
  *
  * @brief Free-running counter and busy wait delay functions.
  *
diff --git a/cpukit/include/rtems/extension.h b/cpukit/include/rtems/extension.h
index 59d4839bf4..6f97ebe24c 100644
--- a/cpukit/include/rtems/extension.h
+++ b/cpukit/include/rtems/extension.h
@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup ClassicUserExtensions
+ * @ingroup RTEMSImplClassicUserExt
  *
  * @brief User Extensions API.
  */
@@ -27,7 +27,7 @@ extern "C" {
 #endif
 
 /**
- * @defgroup ClassicUserExtensions User Extensions
+ * @defgroup RTEMSAPIClassicUserExt User Extensions Manager
  *
  * @ingroup RTEMSAPIClassic
  *
@@ -35,7 +35,7 @@ extern "C" {
  * augment the executive by allowing them to supply extension routines which
  * are invoked at critical system events.
  *
- * @section ClassicUserExtensionsSets Extension Sets
+ * @section RTEMSAPIClassicUserExtSets Extension Sets
  *
  * An @ref User_extensions_Table "extension set" is defined as a set of
  * routines which are invoked at each of the critical system events at which
@@ -75,7 +75,7 @@ extern "C" {
  * Extension switches do not effect the context switch overhead if no switch
  * handler is installed.
  *
- * @section ClassicUserExtensionsTCB Task Control Block Area
+ * @section RTEMSAPIClassicUserExtTCB Task Control Block Area
  *
  * RTEMS provides for a pointer to a user-defined data area for each extension
  * set to be linked to each task's control block (TCB). This area is only
@@ -114,7 +114,7 @@ extern "C" {
  * buffers and use the partition manager's allocation and deallocation
  * directives to obtain and release the extension buffers.
  *
- * @section ClassicUserExtensionsOrder Order of Invokation
+ * @section RTEMSAPIClassicUserExtOrder Order of Invokation
  *
  * When one of the critical system events occur, the user extensions are
  * invoked in either @a forward or @a reverse order. Forward order indicates
diff --git a/cpukit/include/rtems/ioimpl.h b/cpukit/include/rtems/ioimpl.h
index 5c4a82eea6..df2cc8d43e 100644
--- a/cpukit/include/rtems/ioimpl.h
+++ b/cpukit/include/rtems/ioimpl.h
@@ -1,7 +1,10 @@
 /**
  * @file
  *
- * @brief Classic Input/Output Manager Implementation API
+ * @ingroup RTEMSImplClassicIO
+ *
+ * @brief This header file provides interfaces used by the I/O Manager
+ *   implementation.
  */
 
 /*
@@ -23,6 +26,16 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @defgroup RTEMSImplClassicIO I/O Manager
+ *
+ * @ingroup RTEMSImplClassic
+ *
+ * @brief This group contains the I/O Manager implementation.
+ *
+ * @{
+ */
+
 extern const size_t _IO_Number_of_drivers;
 
 extern rtems_driver_address_table _IO_Driver_address_table[];
@@ -58,6 +71,8 @@ RTEMS_INLINE_ROUTINE void _IO_Driver_registration_release(
   );
 }
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/cpukit/include/rtems/profiling.h b/cpukit/include/rtems/profiling.h
index 3bad1eda49..9b4b70489c 100644
--- a/cpukit/include/rtems/profiling.h
+++ b/cpukit/include/rtems/profiling.h
@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @ingroup Profiling
+ * @ingroup RTEMSAPIProfiling
  *
- * @brief Profiling API
+ * @brief This header file provides the Profiling Support API.
  */
 
 /*
@@ -32,7 +32,7 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
- * @defgroup Profiling Profiling Support
+ * @defgroup RTEMSAPIProfiling Profiling Support
  *
  * @ingroup RTEMSAPI
  *
diff --git a/cpukit/include/rtems/rbheap.h b/cpukit/include/rtems/rbheap.h
index d772c1a284..0db72ebf93 100644
--- a/cpukit/include/rtems/rbheap.h
+++ b/cpukit/include/rtems/rbheap.h
@@ -1,7 +1,9 @@
 /**
  * @file
  *
- * @brief Red-Black Tree Heap API
+ * @ingroup RTEMSAPIRBHeap
+ *
+ * @brief This header file provides the Red-Black Tree Heap API.
  */
 
 /*
@@ -30,11 +32,12 @@ extern "C" {
 #endif
 
 /**
- * @defgroup RBHeap Red-Black Tree Heap
+ * @defgroup RTEMSAPIRBHeap Red-Black Tree Heap
  *
- * @ingroup RTEMSAPIClassic
+ * @ingroup RTEMSAPI
  *
- * @brief Red-Black Tree Heap API.
+ * @brief The red-black tree heap provides a memory allocator using a red-black
+ *   tree to maintain blocks of memory.
  *
  * The red-black tree heap provides a memory allocator suitable to implement
  * the malloc() and free() interface.  It uses a first-fit allocation strategy.
diff --git a/cpukit/include/rtems/rbtree.h b/cpukit/include/rtems/rbtree.h
index 6a45037ac3..be3f08c7f1 100644
--- a/cpukit/include/rtems/rbtree.h
+++ b/cpukit/include/rtems/rbtree.h
@@ -1,12 +1,9 @@
 /**
  * @file
  * 
- * @brief Constants and Structures Associated with the RBTree API in RTEMS
- * 
- * This include file contains all the constants and structures associated
- * with the RBTree API in RTEMS. The rbtree is a Red Black Tree that
- * is part of the Super Core. This is the published interface to that
- * code.
+ * @ingroup RTEMSAPIClassicRBTrees
+ *
+ * @brief This header file provides the Red-Black Trees API.
  */
 
 /*
@@ -27,11 +24,12 @@ extern "C" {
 #endif
 
 /**
- * @defgroup ClassicRBTrees Red-Black Trees
+ * @defgroup RTEMSAPIRBTrees Red-Black Trees
  *
  * @ingroup RTEMSAPIClassic
  *
- * @brief A Red-Black Tree container.
+ * @brief The red-black tree container provides data structures and directives
+ *   to manage user-defined data structures in red-black trees.
  *
  * The red-black tree container offers no internal protection against
  * concurrent access.  The user must ensure that at most one thread at once can
diff --git a/cpukit/include/rtems/timecounter.h b/cpukit/include/rtems/timecounter.h
index 8ff18c2da3..d5025d8b1a 100644
--- a/cpukit/include/rtems/timecounter.h
+++ b/cpukit/include/rtems/timecounter.h
@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @ingroup SAPITimecounter
+ * @ingroup RTEMSAPIClassicTimecounter
  *
- * @brief Timecounter API
+ * @brief This header file provides the Timecounter Support API.
  */
 
 /*
@@ -31,10 +31,13 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
- * @defgroup SAPITimecounter Timecounter Support
+ * @defgroup RTEMSAPIClassicTimecounter Timecounter Support
  *
  * @ingroup RTEMSAPIClassic
  *
+ * @brief The timecounter support provides directives to implement clock device
+ *   drivers.
+ *
  * @{
  */
 
diff --git a/cpukit/include/rtems/version.h b/cpukit/include/rtems/version.h
index a8aff732f3..87d5e1492c 100644
--- a/cpukit/include/rtems/version.h
+++ b/cpukit/include/rtems/version.h
@@ -1,7 +1,9 @@
 /**
  * @file
  *
- * @brief Version API.
+ * @ingroup RTEMSAPIClassicVersion
+ *
+ * @brief This header file provides the Version API.
  */
 
 /*
@@ -29,8 +31,9 @@ extern "C" {
  *
  * @brief The Version API provides functions to return the version or parts of
  * the version of RTEMS you are using.
+ *
+ * @{
  */
-/**@{**/
 
 /**
  * @brief Returns the version string.
diff --git a/cpukit/sapi/src/chainappendnotify.c b/cpukit/sapi/src/chainappendnotify.c
index 37a292bfc4..c4f618458e 100644
--- a/cpukit/sapi/src/chainappendnotify.c
+++ b/cpukit/sapi/src/chainappendnotify.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup ClassicChains
+ * @ingroup RTEMSAPIClassicChains
  *
- * @brief rtems_chain_append_with_notification() implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_chain_append_with_notification().
  */
 
 /*
diff --git a/cpukit/sapi/src/chaingetnotify.c b/cpukit/sapi/src/chaingetnotify.c
index d32d87a8bd..004d87443a 100644
--- a/cpukit/sapi/src/chaingetnotify.c
+++ b/cpukit/sapi/src/chaingetnotify.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup ClassicChains
+ * @ingroup RTEMSAPIClassicChains
  *
- * @brief rtems_chain_get_with_notification() implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_chain_get_with_notification().
  */
 
 /*
diff --git a/cpukit/sapi/src/chaingetwait.c b/cpukit/sapi/src/chaingetwait.c
index 8164665479..a62c7f748e 100644
--- a/cpukit/sapi/src/chaingetwait.c
+++ b/cpukit/sapi/src/chaingetwait.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup ClassicChains
+ * @ingroup RTEMSAPIClassicChains
  *
- * @brief rtems_chain_get_with_wait() implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_chain_get_with_wait().
  */
 
 /*
diff --git a/cpukit/sapi/src/chainprependnotify.c b/cpukit/sapi/src/chainprependnotify.c
index bf11abde11..c08bb627af 100644
--- a/cpukit/sapi/src/chainprependnotify.c
+++ b/cpukit/sapi/src/chainprependnotify.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup ClassicChains
+ * @ingroup RTEMSAPIClassicChains
  *
- * @brief rtems_chain_prepend_with_notification() implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_chain_prepend_with_notification().
  */
 
 /*
diff --git a/cpukit/sapi/src/chainprotected.c b/cpukit/sapi/src/chainprotected.c
index 73457e6cc1..54b4140250 100644
--- a/cpukit/sapi/src/chainprotected.c
+++ b/cpukit/sapi/src/chainprotected.c
@@ -1,3 +1,15 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPIClassicChains
+ *
+ * @brief This source file contains the implementation of rtems_chain_append(),
+ *   rtems_chain_append_with_empty_check(), rtems_chain_extract(),
+ *   rtems_chain_get(), rtems_chain_get_with_empty_check(),
+ *   rtems_chain_insert(), rtems_chain_prepend(), and
+ *   rtems_chain_prepend_with_empty_check().
+ */
+
 /*
  * Copyright (c) 2013, 2016 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/sapi/src/delaynano.c b/cpukit/sapi/src/delaynano.c
index 6d7ebf48f8..e6fc742a50 100644
--- a/cpukit/sapi/src/delaynano.c
+++ b/cpukit/sapi/src/delaynano.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPICounter
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_counter_delay_nanoseconds().
+ */
+
 /*
  * Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/sapi/src/delayticks.c b/cpukit/sapi/src/delayticks.c
index ea20bb6766..8fec35173e 100644
--- a/cpukit/sapi/src/delayticks.c
+++ b/cpukit/sapi/src/delayticks.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPICounter
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_counter_delay_ticks().
+ */
+
 /*
  * Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/sapi/src/exinit.c b/cpukit/sapi/src/exinit.c
index db0d1fb70d..acb2041e1e 100644
--- a/cpukit/sapi/src/exinit.c
+++ b/cpukit/sapi/src/exinit.c
@@ -1,9 +1,12 @@
 /**
  * @file
  *
- * @brief Initialization Manager
+ * @ingroup RTEMSImplClassic
  *
- * @ingroup ClassicRTEMS
+ * @brief This source file contains the definition of ::_Copyright_Notice,
+ *   ::_Objects_Information_table, the flexible per-CPU data linker set limits,
+ *   the system initialization linker set limits and the implementation of
+ *   rtems_initialize_executive().
  */
 
 /*
diff --git a/cpukit/sapi/src/exshutdown.c b/cpukit/sapi/src/exshutdown.c
index addd53e9dd..0297cad104 100644
--- a/cpukit/sapi/src/exshutdown.c
+++ b/cpukit/sapi/src/exshutdown.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSImplClassic
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_shutdown_executive().
+ */
+
 /*
  *  Initialization Manager
  *
diff --git a/cpukit/sapi/src/extension.c b/cpukit/sapi/src/extension.c
index 85e327c1b9..6effe2efd3 100644
--- a/cpukit/sapi/src/extension.c
+++ b/cpukit/sapi/src/extension.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup ClassicUserExtensions
+ * @ingroup RTEMSImplClassicUserExt
  *
- * @brief Extension Manager Information with Zero Objects
+ * @brief This source file contains a definition of the
+ *   ::_Extension_Information with zero objects.
  */
 
 /*
diff --git a/cpukit/sapi/src/extensioncreate.c b/cpukit/sapi/src/extensioncreate.c
index 5751f47bef..73ea91a8e1 100644
--- a/cpukit/sapi/src/extensioncreate.c
+++ b/cpukit/sapi/src/extensioncreate.c
@@ -1,9 +1,11 @@
 /**
  * @file
  *
- * @ingroup ClassicUserExtensions
+ * @ingroup RTEMSImplClassicUserExt
  *
- * @brief User Extensions Implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_extension_create() and the User Extensions Manager system
+ *   initialization.
  */
 
 /*
diff --git a/cpukit/sapi/src/extensiondelete.c b/cpukit/sapi/src/extensiondelete.c
index 0ea6115e6c..9b5454bfc5 100644
--- a/cpukit/sapi/src/extensiondelete.c
+++ b/cpukit/sapi/src/extensiondelete.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup ClassicUserExtensions
+ * @ingroup RTEMSImplClassicUserExt
  *
- * @brief User Extensions Implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_extension_delete().
  */
 
 /*
diff --git a/cpukit/sapi/src/extensionident.c b/cpukit/sapi/src/extensionident.c
index aa0dfca5ab..5b2eb746d4 100644
--- a/cpukit/sapi/src/extensionident.c
+++ b/cpukit/sapi/src/extensionident.c
@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplClassicUserExt
  *
- * @brief rtems_extension_ident() Implementation
+ * @brief This source file contains the implementation of
+ *   rtems_extension_ident().
  */
 
 /*
diff --git a/cpukit/sapi/src/fatal.c b/cpukit/sapi/src/fatal.c
index d834f739e4..6e4c452e5d 100644
--- a/cpukit/sapi/src/fatal.c
+++ b/cpukit/sapi/src/fatal.c
@@ -1,10 +1,10 @@
 /**
  * @file
  *
- * @brief Invokes the internal error handler with a source of
- *        INTERNAL_ERROR_RTEMS_API and is internal set to false.
+ * @ingroup RTEMSImplClassic
  *
- * @ingroup ClassicFatal
+ * @brief This source file contains the implementation of
+ *   rtems_fatal_error_occurred().
  */
 
 /*
diff --git a/cpukit/sapi/src/fatalsrctext.c b/cpukit/sapi/src/fatalsrctext.c
index 4d06415e2a..6510725e13 100644
--- a/cpukit/sapi/src/fatalsrctext.c
+++ b/cpukit/sapi/src/fatalsrctext.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Implementation of rtems_fatal_source_text()
+ * @ingroup RTEMSImplClassic
  *
- * @ingroup ClassicFatal
+ * @brief This source file contains the implementation of
+ *   rtems_fatal_source_text().
  */
 
 /*
diff --git a/cpukit/sapi/src/getconfigmax.c b/cpukit/sapi/src/getconfigmax.c
index 4d2779dc85..8e3cce67f1 100644
--- a/cpukit/sapi/src/getconfigmax.c
+++ b/cpukit/sapi/src/getconfigmax.c
@@ -1,6 +1,24 @@
-/*
- * SPDX-License-Identifier: BSD-2-Clause
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @ingroup RTEMSImplClassic
  *
+ * @brief This source file contains the implementation of
+ *   rtems_configuration_get_maximum_barriers(),
+ *   rtems_configuration_get_maximum_extensions(),
+ *   rtems_configuration_get_maximum_message_queues(),
+ *   rtems_configuration_get_maximum_partitions(),
+ *   rtems_configuration_get_maximum_periods(),
+ *   rtems_configuration_get_maximum_ports(),
+ *   rtems_configuration_get_maximum_regions(),
+ *   rtems_configuration_get_maximum_semaphores(),
+ *   rtems_configuration_get_maximum_tasks(), and
+ *   rtems_configuration_get_maximum_timers().
+ */
+
+/*
  * Copyright (C) 2018 embedded brains GmbH
  *
  * Redistribution and use in source and binary forms, with or without
diff --git a/cpukit/sapi/src/getcopyrightnotice.c b/cpukit/sapi/src/getcopyrightnotice.c
index cd601254e6..936f0f817b 100644
--- a/cpukit/sapi/src/getcopyrightnotice.c
+++ b/cpukit/sapi/src/getcopyrightnotice.c
@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @ingroup RTEMSAPIClassic
+ * @ingroup RTEMSImplClassic
  *
- * @brief rtems_get_copyright_notice() Implementation
+ * @brief This source file contains the implementation of
+ *   rtems_get_copyright_notice().
  */
 
 /*
diff --git a/cpukit/sapi/src/getversionstring.c b/cpukit/sapi/src/getversionstring.c
index f8380f7b4f..5a68f5e3ff 100644
--- a/cpukit/sapi/src/getversionstring.c
+++ b/cpukit/sapi/src/getversionstring.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Get the RTEMS Version as a String
+ * @ingroup RTEMSImplClassic
  *
- * @ingroup ClassicRTEMS
+ * @brief This source file contains the implementation of
+ *   rtems_get_version_string().
  */
 
 /*
diff --git a/cpukit/sapi/src/interrtext.c b/cpukit/sapi/src/interrtext.c
index 654b3110ad..2a588a5b76 100644
--- a/cpukit/sapi/src/interrtext.c
+++ b/cpukit/sapi/src/interrtext.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Returns a text for an internal error code.
+ * @ingroup RTEMSImplClassic
  *
- * @ingroup ClassicFatal
+ * @brief This source file contains the implementation of
+ *   rtems_internal_error_text().
  */
 
 /*
diff --git a/cpukit/sapi/src/io.c b/cpukit/sapi/src/io.c
index 63b784e723..78b71ec0f8 100644
--- a/cpukit/sapi/src/io.c
+++ b/cpukit/sapi/src/io.c
@@ -1,9 +1,11 @@
 /**
  * @file
  *
- * @brief Initialization of Device Drivers
+ * @ingroup RTEMSImplClassicIO
  *
- * @ingroup ClassicIO
+ * @brief This source file contains the definition of
+ *   ::_IO_All_drivers_initialized and implementation of
+ *   _IO_Initialize_all_drivers().
  */
 
 /*
diff --git a/cpukit/sapi/src/ioclose.c b/cpukit/sapi/src/ioclose.c
index 151d675b55..faa9657816 100644
--- a/cpukit/sapi/src/ioclose.c
+++ b/cpukit/sapi/src/ioclose.c
@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @brief Closing for The IO Manager
+ * @ingroup RTEMSImplClassicIO
  *
- * @ingroup ClassicIO
+ * @brief This source file contains the implementation of rtems_io_close().
  */
 
 /*
diff --git a/cpukit/sapi/src/iocontrol.c b/cpukit/sapi/src/iocontrol.c
index 60939184aa..9076ac9d02 100644
--- a/cpukit/sapi/src/iocontrol.c
+++ b/cpukit/sapi/src/iocontrol.c
@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @brief Control for The IO Manager
+ * @ingroup RTEMSImplClassicIO
  *
- * @ingroup ClassicIO
+ * @brief This source file contains the implementation of rtems_io_control().
  */
 
 /*
diff --git a/cpukit/sapi/src/iodefault.c b/cpukit/sapi/src/iodefault.c
index fac613e43c..8ccc6b4519 100644
--- a/cpukit/sapi/src/iodefault.c
+++ b/cpukit/sapi/src/iodefault.c
@@ -3,10 +3,10 @@
 /**
  * @file
  *
- * @ingroup ClassicIO
+ * @ingroup RTEMSImplClassicIO
  *
- * @brief This file contains definitions of IO drivers data structures for the
- * default application configuration.
+ * @brief This source file contains a definition of ::_IO_Driver_address_table
+ *   and ::_IO_Number_of_drivers with zero drivers.
  */
 
 /*
diff --git a/cpukit/sapi/src/ioinitialize.c b/cpukit/sapi/src/ioinitialize.c
index 1648533c77..af8e7881bd 100644
--- a/cpukit/sapi/src/ioinitialize.c
+++ b/cpukit/sapi/src/ioinitialize.c
@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @brief IO Driver Initialization
+ * @ingroup RTEMSImplClassicIO
  *
- * @ingroup ClassicIO
+ * @brief This source file contains the implementation of rtems_io_initialize().
  */
 
 /*
diff --git a/cpukit/sapi/src/ioopen.c b/cpukit/sapi/src/ioopen.c
index a42d9f12b4..01ed0e2bc9 100644
--- a/cpukit/sapi/src/ioopen.c
+++ b/cpukit/sapi/src/ioopen.c
@@ -1,14 +1,12 @@
 /**
  * @file
  *
- * @brief Opening for The IO Manager
+ * @ingroup RTEMSImplClassicIO
  *
- * @ingroup ClassicIO
+ * @brief This source file contains the implementation of rtems_io_open().
  */
 
 /*
- *  Input/Output Manager - Open Device
- *
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/sapi/src/ioread.c b/cpukit/sapi/src/ioread.c
index a52c03b389..113018457f 100644
--- a/cpukit/sapi/src/ioread.c
+++ b/cpukit/sapi/src/ioread.c
@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @brief Reading for The IO Manager
+ * @ingroup RTEMSImplClassicIO
  *
- * @ingroup ClassicIO
+ * @brief This source file contains the implementation of rtems_io_read().
  */
 
 /*
diff --git a/cpukit/sapi/src/ioregisterdriver.c b/cpukit/sapi/src/ioregisterdriver.c
index 57d01eec86..2a4ea21a09 100644
--- a/cpukit/sapi/src/ioregisterdriver.c
+++ b/cpukit/sapi/src/ioregisterdriver.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup ClassicIO
+ * @ingroup RTEMSImplClassicIO
  *
- * @brief Classic Input/Output Manager implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_io_register_driver().
  */
 
 /*
diff --git a/cpukit/sapi/src/iounregisterdriver.c b/cpukit/sapi/src/iounregisterdriver.c
index 75cbe9a6b8..8fa3241945 100644
--- a/cpukit/sapi/src/iounregisterdriver.c
+++ b/cpukit/sapi/src/iounregisterdriver.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Unregister a Driver from the Device Driver Table.
+ * @ingroup RTEMSImplClassicIO
  *
- * @ingroup ClassicIO
+ * @brief This source file contains the implementation of
+ *   rtems_io_unregister_driver().
  */
 
 /*
diff --git a/cpukit/sapi/src/iowrite.c b/cpukit/sapi/src/iowrite.c
index 79b1888b40..a5d26a7dd5 100644
--- a/cpukit/sapi/src/iowrite.c
+++ b/cpukit/sapi/src/iowrite.c
@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @brief Writing for The IO Manager
+ * @ingroup RTEMSImplClassicIO
  *
- * @ingroup ClassicIO
+ * @brief This source file contains the implementation of rtems_io_write().
  */
 
 /*
diff --git a/cpukit/sapi/src/panic.c b/cpukit/sapi/src/panic.c
index e18765a5d2..cca88de836 100644
--- a/cpukit/sapi/src/panic.c
+++ b/cpukit/sapi/src/panic.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup ErrorPanicSupport
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_panic().
+ */
+
 /*
  * Copyright (c) 2017 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/sapi/src/profilingiterate.c b/cpukit/sapi/src/profilingiterate.c
index 1f2a3752aa..0af1beefa9 100644
--- a/cpukit/sapi/src/profilingiterate.c
+++ b/cpukit/sapi/src/profilingiterate.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPIProfiling
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_profiling_iterate().
+ */
+
 /*
  * Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/sapi/src/profilingreportxml.c b/cpukit/sapi/src/profilingreportxml.c
index f89fb8bd71..8468ee2c59 100644
--- a/cpukit/sapi/src/profilingreportxml.c
+++ b/cpukit/sapi/src/profilingreportxml.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPIProfiling
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_profiling_report_xml().
+ */
+
 /*
  * Copyright (c) 2014 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/sapi/src/rbheap.c b/cpukit/sapi/src/rbheap.c
index 46de7346c3..be25536909 100644
--- a/cpukit/sapi/src/rbheap.c
+++ b/cpukit/sapi/src/rbheap.c
@@ -1,9 +1,12 @@
 /**
  * @file
  *
- * @ingroup RBHeap
+ * @ingroup RTEMSAPIRBHeap
  *
- * @brief Red-Black Tree Heap implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_rbheap_allocate(), rtems_rbheap_extend_descriptors_never(),
+ *   rtems_rbheap_extend_descriptors_with_malloc(), rtems_rbheap_free(), and
+ *   rtems_rbheap_initialize().
  */
 
 /*
diff --git a/cpukit/sapi/src/rbtree.c b/cpukit/sapi/src/rbtree.c
index 829a57c2b5..a632efb554 100644
--- a/cpukit/sapi/src/rbtree.c
+++ b/cpukit/sapi/src/rbtree.c
@@ -1,8 +1,10 @@
 /**
- *  @file
+ * @file
  *
- *  @brief Initialize a Red-Black Tree
- *  @ingroup ClassicRBTrees
+ * @ingroup RTEMSAPIClassicRBTrees
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_rbtree_initialize().
  */
 
 /*
diff --git a/cpukit/sapi/src/rbtreefind.c b/cpukit/sapi/src/rbtreefind.c
index 7c8fcb8952..e043618621 100644
--- a/cpukit/sapi/src/rbtreefind.c
+++ b/cpukit/sapi/src/rbtreefind.c
@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup RTEMSScorertems_rbtree
+ * @ingroup RTEMSAPIClassicRBTrees
  *
- * @brief Find the control structure of the tree containing the given node
+ * @brief This source file contains the implementation of
+ *   rtems_rbtree_find().
  */
 
 /*
diff --git a/cpukit/sapi/src/sapirbtreeinsert.c b/cpukit/sapi/src/sapirbtreeinsert.c
index 926b80a41d..e470bc2c09 100644
--- a/cpukit/sapi/src/sapirbtreeinsert.c
+++ b/cpukit/sapi/src/sapirbtreeinsert.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPIClassicRBTrees
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_rbtree_insert().
+ */
+
 /*
  *  Copyright (c) 2010-2012 Gedare Bloom.
  *
diff --git a/cpukit/sapi/src/sysinitverbose.c b/cpukit/sapi/src/sysinitverbose.c
index 50bc152bfd..157889c814 100644
--- a/cpukit/sapi/src/sysinitverbose.c
+++ b/cpukit/sapi/src/sysinitverbose.c
@@ -1,6 +1,15 @@
-/*
- * SPDX-License-Identifier: BSD-2-Clause
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @ingroup RTEMSImplClassic
  *
+ * @brief This source file contains the implementation of
+ *   _Sysinit_Verbose().
+ */
+
+/*
  * Copyright (C) 2020 embedded brains GmbH
  *
  * Redistribution and use in source and binary forms, with or without
diff --git a/cpukit/sapi/src/tcsimpleinstall.c b/cpukit/sapi/src/tcsimpleinstall.c
index 80dd4ca72a..adde036ff8 100644
--- a/cpukit/sapi/src/tcsimpleinstall.c
+++ b/cpukit/sapi/src/tcsimpleinstall.c
@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSAPIClassicTimecounter
+ *
+ * @brief This source file contains the implementation of
+ *   rtems_timecounter_simple_install().
+ */
+
 /*
  * Copyright (c) 2015 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/sapi/src/version.c b/cpukit/sapi/src/version.c
index 9c10ff3823..feafe7b935 100644
--- a/cpukit/sapi/src/version.c
+++ b/cpukit/sapi/src/version.c
@@ -1,14 +1,18 @@
 /**
  * @file
  *
- * @brief Creates the version strings from the various pieces of version
- * information. The main version number is part of the build system and is
- * stamped into rtems/score/cpuopts.h. The version control key string is
- * extracted from the version control tool when the code is being built and is
- * updated if it has changed. The key may indicate there are local
- * modification.
- *
  * @ingroup RTEMSAPIClassicVersion
+ *
+ * @brief This source file contains the implementation of rtems_version(),
+ *   rtems_version_control_key(), rtems_version_major(), rtems_version_minor(),
+ *   and rtems_version_revision().
+ *
+ * The version strings are created from the various pieces of version
+ * information.  The main version number is part of the build system and is
+ * stamped into <rtems/score/cpuopts.h>.  The version control key string is
+ * extracted from the version control tool when the code is being built and is
+ * updated if it has changed.  It is defined in "version-vc-key.h".  The key
+ * may indicate there are local modification.
  */
 
 /*
-- 
2.26.2

More information about the devel mailing list