score: Canonicalize Doxygen groups

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

Update #3706.

cpukit/include/rtems/score/address.h

@@ -32,7 +32,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Support for Address Manipulation
+ * @brief This group contains the Address Handler implementation.
  *
  * This handler encapsulates functionality which abstracts address
  * manipulation in a portable manner.

cpukit/include/rtems/score/apimutex.h

@@ -27,7 +27,10 @@
  *
  * @ingroup RTEMSScore
  *
- * @brief Provides routines to ensure mutual exclusion on API level.
+ * @brief This group contains the API Mutex Handler implementation.
+ *
+ * This handler provides routines to ensure mutual exclusion in a thread
+ * context at the API level.
  *
  * @{
  */

cpukit/include/rtems/score/assert.h

@@ -30,7 +30,7 @@
  *
  * @ingroup RTEMSScore
  *
- * @brief Support for Assert Statements
+ * @brief This group contains the Assert Handler implementation.
  *
  * @{
  */

cpukit/include/rtems/score/atomic.h

@@ -24,7 +24,7 @@
  *
  * @ingroup RTEMSScore
  *
- * @brief Support for atomic operations.
+ * @brief This group contains the atomic operations implementation.
  *
  * Atomic operations can be used to implement low-level synchronization
  * primitives on SMP systems, like spin locks.  All atomic operations are

cpukit/include/rtems/score/chain.h

@@ -29,7 +29,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Provides Data Structures Chain Node and Chain Control
+ * @brief This group contains the Chain Handler implementation.
  *
  * The Chain Handler is used to manage sets of entities.  This handler
  * provides two data structures.  The Chain Node data structure is included

cpukit/include/rtems/score/context.h

@@ -25,7 +25,7 @@
  *
  * @ingroup RTEMSScore
  *
- * @brief Functionality for Abstraction of Thread Context Management
+ * @brief This group contains the Context Handler implementation.
  *
  * This handler encapsulates functionality which abstracts thread context
  * management in a portable manner.

cpukit/include/rtems/score/copyrt.h

@@ -22,11 +22,12 @@
 #define _RTEMS_SCORE_COPYRT_H
 
 /**
- * @defgroup RTEMSSuperCoreCopyright RTEMS Copyright Notice
+ * @defgroup RTEMSScoreCopyright Copyright Notice
  *
  * @ingroup RTEMSScore
  *
- * @brief Copyright Notice for RTEMS
+ * @brief This group contains the implementation to provide a copyright notice
+ *   and the RTEMS version.
  *
  * @{
  */
@@ -37,7 +38,7 @@ extern "C" {
 #endif
 
 /**
- *  This is the copyright string for RTEMS.
+ * @brief This is the copyright string for RTEMS.
  */
 extern const char _Copyright_Notice[];
 

cpukit/include/rtems/score/corebarrier.h

@@ -32,7 +32,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Functionality for Foundation Barrier Services
+ * @brief This group contains the Barrier Handler implementation.
  *
  * This handler encapsulates functionality which provides the foundation
  * Barrier services used in all of the APIs supported by RTEMS.

cpukit/include/rtems/score/coremsg.h

@@ -35,7 +35,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Message Queue Handler
+ * @brief This group contains the Message Queue Handler implementation.
  *
  * This handler encapsulates functionality which provides the foundation
  * Message Queue services used in all of the APIs supported by RTEMS.

cpukit/include/rtems/score/coremutex.h

@@ -40,7 +40,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Mutex Handler
+ * @brief This group contains the Mutex Handler implementation.
  *
  * This handler encapsulates functionality which provides the foundation
  * Mutex services used in all of the APIs supported by RTEMS.

cpukit/include/rtems/score/corerwlockimpl.h

@@ -28,13 +28,14 @@
 #include <rtems/score/watchdog.h>
 
 /**
- * @defgroup RTEMSScoreRWLock ScoreRWLock
- * 
+ * @defgroup RTEMSScoreRWLock Read-Write Lock
+ *
  * @ingroup RTEMSScore
- * 
- * @brief ScoreRWLock
+ *
+ * @brief This group contains the Read-Write Lock implementation.
+ *
+ * @{
  */
-/** @{ */
 
 #ifdef __cplusplus
 extern "C" {

cpukit/include/rtems/score/coresem.h

@@ -34,7 +34,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Semaphore Handler
+ * @brief This group contains the Semaphore Handler implementation.
  *
  * This handler encapsulates functionality which provides the foundation
  * Semaphore services used in all of the APIs supported by RTEMS.

cpukit/include/rtems/score/cpustdatomic.h

@@ -19,11 +19,12 @@
 #include <rtems/score/basedefs.h>
 
 /**
- * @defgroup RTEMSScoreCPUAtomic Atomic Operations CPU
+ * @defgroup RTEMSScoreAtomicCPU C11/C++11 Atomic Operations
  *
- * @ingroup RTEMSScore
+ * @ingroup RTEMSScoreAtomic
  *
- * @brief Atomic Operations CPU API
+ * @brief This group contains the atomic operations implementation using
+ *   functions provided by the C11/C++11.
  *
  * @{
  */

cpukit/include/rtems/score/freechain.h

@@ -27,11 +27,11 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief The Freechain Handler.
+ * @brief This group contains the Freechain Handler implementation.
  *
- * The Freechain Handler is used to manage a chain of nodes, of which size can
- * automatically increase when there is no free node left. This handler
- * provides one data structure: Freechain_Control.
+ * This handler encapsulates functionality related to the management of
+ * free nodes of a user-defined size.  If the chain of free nodes is empty
+ * during an allocation request, it can be dynamically extended.
  *
  * @{
  */

cpukit/include/rtems/score/heap.h

@@ -34,7 +34,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief The Heap Handler provides a heap.
+ * @brief This group contains the Heap Handler implementation.
  *
  * A heap is a doubly linked list of variable size blocks which are allocated
  * using the first fit method.  Garbage collection is performed each time a

cpukit/include/rtems/score/interr.h

@@ -28,10 +28,9 @@
  *
  * @ingroup RTEMSScore
  *
- * @brief Internal Error Handler
+ * @brief This group contains the Internal Error Handler implementation.
  *
- * This handler encapsulates functionality which provides the foundation
- * Semaphore services used in all of the APIs supported by RTEMS.
+ * This handler encapsulates functionality to terminate the system.
  *
  * @{
  */

cpukit/include/rtems/score/io.h

@@ -23,6 +23,16 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @defgroup RTEMSScoreIO IO Handler
+ *
+ * @ingroup RTEMSScore
+ *
+ * @brief This group contains the IO Handler implementation.
+ *
+ * @{
+ */
+
 typedef void ( *IO_Put_char )( int c, void *arg );
 
 int _IO_Printf(
@@ -64,6 +74,8 @@ int _IO_Base64(
   int          wordlen
 );
 
+/** @} */ 
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */

cpukit/include/rtems/score/isr.h

@@ -30,13 +30,12 @@
  *
  * @ingroup RTEMSScore
  *
- * @brief ISR Handler
+ * @brief This group contains the ISR Handler implementation.
  *
  * This handler encapsulates functionality which provides the foundation
  * ISR services used in all of the APIs supported by RTEMS.
  *
- * The ISR Nest level counter variable is maintained as part of the
- * per cpu data structure.
+ * The ::_ISR_Nest_level variable is maintained by @ref RTEMSScorePerCPU.
  *
  * @{
  */

cpukit/include/rtems/score/isrlock.h

@@ -35,13 +35,15 @@ extern "C" {
  *
  * @ingroup RTEMSScoreISR
  *
- * @brief Low-level lock to protect critical sections accessed by threads and
- * interrupt service routines.
+ * @brief This group contains the ISR locks implementation.
  *
- * On single processor configurations the ISR locks degrade to simple ISR
+ * The ISR locks are low-level locks to protect critical sections accessed by
+ * threads and interrupt service routines.
+ *
+ * In uniprocessor configurations the ISR locks degrade to simple ISR
  * disable/enable sequences.  No additional storage or objects are required.
  *
- * This synchronization primitive is supported on SMP configurations.  Here SMP
+ * This synchronization primitive is supported in SMP configurations.  Here SMP
  * locks are used.
  *
  * @{

cpukit/include/rtems/score/memory.h

@@ -48,8 +48,10 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Low level handler to provide memory areas for higher level memory
- * handlers such as the Workspace Handler.
+ * @brief This group contains the Memory Handler implementation.
+ *
+ * The Memory Handler provides memory areas supplied by the BSP to higher level memory
+ * consumers such as the @ref RTEMSScoreWorkspace and the @ref MallocSupport.
  *
  * @{
  */

cpukit/include/rtems/score/mpci.h

@@ -32,7 +32,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief MPCI Handler
+ * @brief This group contains the MPCI Handler implementation.
  *
  * The MPCI Handler encapsulates functionality which is related to the
  * generation, receipt, and processing of remote operations in a

cpukit/include/rtems/score/mppkt.h

@@ -33,11 +33,12 @@ extern "C" {
 #endif
 
 /**
- * @defgroup RTEMSScoreMPPacket MP Packet Handler
+ * @defgroup RTEMSScoreMPPacket Multiprocessing (MP) Packet Handler
  *
- * @ingroup RTEMSScore
+ * @ingroup RTEMSScoreMPCI
  *
- * @brief MP Packte Handler
+ * @brief This group contains the Multiprocessing (MP) Packet Handler
+ *   implementation.
  *
  * This handler encapsulates the primary definition of MPCI packets.  This
  * handler defines the part of the packet that is common to all remote

cpukit/include/rtems/score/mrsp.h

@@ -34,11 +34,12 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
- * @defgroup RTEMSScoreMRSP Multiprocessor Resource Sharing Protocol Handler
+ * @defgroup RTEMSScoreMRSP Multiprocessor Resource Sharing Protocol (MrsP)
  *
  * @ingroup RTEMSScore
  *
- * @brief Multiprocessor Resource Sharing Protocol (MrsP).
+ * @brief This group contains the implementation to support the Multiprocessor
+ *   Resource Sharing Protocol (MrsP) .
  *
  * The Multiprocessor Resource Sharing Protocol (MrsP) is defined in A.  Burns
  * and A.J.  Wellings, A Schedulability Compatible Multiprocessor Resource

cpukit/include/rtems/score/object.h

@@ -34,9 +34,9 @@ extern "C" {
  *
  * @ingroup RTEMSImpl
  *
- * @brief Provides services for all APIs.
+ * @brief This group contains the SuperCore implementation.
  *
- * @{
+ * The SuperCore provides services for all APIs.
  */
 
 /**
@@ -44,9 +44,8 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Provides CPU architecture dependent services.
- *
- * @{
+ * @brief This group contains the implementation to support a processor
+ *   architecture.
  */
 
 /**
@@ -54,6 +53,8 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
+ * @brief This group contains the Object Handler implementation.
+ *
  * @{
  */
 
@@ -347,8 +348,6 @@ extern uint16_t _Objects_Local_node;
 #define _Objects_Local_node ((uint16_t) 1)
 #endif
 
-/** @} */
-/** @} */
 /** @} */
 
 #ifdef __cplusplus

cpukit/include/rtems/score/objectmp.h

@@ -32,11 +32,12 @@ extern "C" {
 #endif
 
 /**
- * @defgroup RTEMSScoreObjectMP Object Handler Multiprocessing Support
+ * @defgroup RTEMSScoreObjectMP Object Handler Multiprocessing (MP) Support
  *
- * @ingroup RTEMSScore
+ * @ingroup RTEMSScoreObject
  *
- * @brief Object Handler Multiprocessing Support
+ * @brief This group contains the implementation to support the Object Handler
+ *   in multiprocessing (MP) configurations.
  *
  * This handler encapsulates functionality which is used to manage
  * objects which have been declared to be globally visible.  This handler

cpukit/include/rtems/score/onceimpl.h

@@ -30,11 +30,12 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
- * @defgroup RTEMSScoreOnce Once Functions.
+ * @defgroup RTEMSScoreOnce Execute Once Support
  *
  * @ingroup RTEMSScore
  *
- * @brief The _Once() function for pthread_once() and rtems_gxx_once().
+ * @brief This group contains the implementation to execute a routine only
+ *   once.
  *
  * @{
  */

cpukit/include/rtems/score/percpu.h

@@ -78,14 +78,16 @@ struct _Thread_Control;
 struct Scheduler_Context;
 
 /**
- *  @defgroup PerCPU RTEMS Per CPU Information
+ * @defgroup RTEMSScorePerCPU Per-CPU Information
  *
- *  @ingroup RTEMSScore
+ * @ingroup RTEMSScore
  *
- *  This defines the per CPU state information required by RTEMS
- *  and the BSP.  In an SMP configuration, there will be multiple
- *  instances of this data structure -- one per CPU -- and the
- *  current CPU number will be used as the index.
+ * @brief This group contains the implementation of the per-CPU information.
+ *
+ * The per-CPU information encapsulates state which is maintained for each
+ * configured processor in the system.  There will be one instance of a
+ * ::Per_CPU_Control in the ::_Per_CPU_Information table for each configured
+ * processor in the system.
  */
 
 /**@{*/

cpukit/include/rtems/score/percpudata.h

@@ -1,9 +1,9 @@
 /**
  * @file
  *
- * @ingroup PerCPUData
+ * @ingroup RTEMSScorePerCPUData
  *
- * @brief Definition of custom per-CPU items.
+ * @brief This header file provides the Flexible Per-CPU Data API.
  */
 
 /*
@@ -31,14 +31,15 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
- * @defgroup PerCPUData Flexible Per-CPU Data
+ * @defgroup RTEMSScorePerCPUData Flexible Per-CPU Data
  *
- * @ingroup PerCPU
+ * @ingroup RTEMSScorePerCPU
  *
- * @brief Flexible Per-CPU Data
+ * @brief This group contains the implementation to support flexible per-CPU
+ *   data.
  *
- * Provides the definition of custom per-CPU items.  The items are collected in
- * a special linker set.  During system initialization the content of the
+ * Macros to define custom per-CPU items are provided.  The items are collected
+ * in a special linker set.  During system initialization the content of the
  * linker set is duplicated for all secondary processors using memory allocated
  * from the workspace.  The begin and end of the per-CPU data area is cache
  * line aligned (CPU_CACHE_LINE_BYTES).

cpukit/include/rtems/score/priority.h

@@ -35,7 +35,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Priority Handler
+ * @brief This group contains the Priority Handler implementation.
  *
  * This handler encapsulates functionality which is used to manage thread
  * priorities.  The actual priority of a thread is an aggregation of priority

cpukit/include/rtems/score/prioritybitmap.h

@@ -28,9 +28,9 @@ extern "C" {
 #endif
 
 /**
- * @defgroup RTEMSScorePriorityBitmap Bitmap Priority Thread Routines
+ * @defgroup RTEMSScorePriorityBitmap Priority Bitmap
  *
- * @brief Bitmap Priority Thread Routines
+ * @brief This group contains the implementation to support priority bitmaps.
  *
  * @ingroup RTEMSScore
  *

cpukit/include/rtems/score/prioritybitmapimpl.h

@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup RTEMSScorePriority
+ * @ingroup RTEMSScorePriorityBitmap
  *
  * @brief Inlined Routines in the Priority Handler Bit Map Implementation
  *

cpukit/include/rtems/score/processormask.h

@@ -38,7 +38,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Processor Mask
+ * @brief This group contains the implementation to support processor masks.
  *
  * The processor mask provides a bit map large enough to provide one bit for
  * each processor in the system.  It is a fixed size internal data type

cpukit/include/rtems/score/profiling.h

@@ -35,7 +35,7 @@ extern "C" {
  * 
  * @ingroup RTEMSScore
  *
- * @brief Profiling support.
+ * @brief This group contains the implementation to support profiling.
  *
  * @{
  */

cpukit/include/rtems/score/protectedheap.h

@@ -30,7 +30,7 @@ extern "C" {
  *
  * @ingroup RTEMSScoreHeap
  *
- * @brief Provides protected heap services.
+ * @brief This group contains the Protected Heap Handler implementation.
  *
  * The @ref ScoreAllocatorMutex is used to protect the heap accesses.
  *

cpukit/include/rtems/score/rbtree.h

@@ -33,7 +33,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief Red-Black Tree Handler.
+ * @brief This group contains the Red-Black Tree Handler implementation.
  *
  * The Red-Black Tree Handler is used to manage sets of entities.  This handler
  * provides two data structures.  The rbtree Node data structure is included

cpukit/include/rtems/score/schedulercbs.h

@@ -35,11 +35,12 @@ extern "C" {
 #endif
 
 /**
- * @defgroup RTEMSScoreSchedulerCBS CBS Scheduler
+ * @defgroup RTEMSScoreSchedulerCBS Constant Bandwidth Server (CBS) Scheduler
  *
  * @ingroup RTEMSScoreScheduler
  *
- * @brief CBS Scheduler.
+ * @brief This group contains the Constant Bandwidth Server (CBS) Scheduler
+ *   implementation.
  *
  * @{
  */

cpukit/include/rtems/score/scheduleredf.h

@@ -37,7 +37,7 @@ extern "C" {
  *
  * @ingroup RTEMSScoreScheduler
  *
- * @brief EDF Scheduler
+ * @brief This group contains the EDF Scheduler implementation.
  *
  * @{
  */

cpukit/include/rtems/score/scheduleredfsmp.h

@@ -26,11 +26,12 @@ extern "C" {
 #endif
 
 /**
- * @defgroup RTEMSScoreSchedulerSMPEDF EDF Priority SMP Scheduler
+ * @defgroup RTEMSScoreSchedulerSMPEDF Earliest Deadline First (EDF) Priority SMP Scheduler
  *
  * @ingroup RTEMSScoreSchedulerSMP
  *
- * @brief EDF Priority SMP Scheduler
+ * @brief This group contains the Earliest Deadline First (EDF) Priority SMP
+ *   Scheduler implementation.
  *
  * @{
  */

cpukit/include/rtems/score/schedulerimpl.h

@@ -38,8 +38,10 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief This handler encapsulates functionality related to managing sets of
- *   threads that are ready for execution.
+ * @brief This group contains the Scheduler Handler implementation.
+ *
+ * This handler encapsulates functionality related to managing sets of threads
+ * that are ready for execution.
  *
  * Schedulers are used by the system to manage sets of threads that are ready
  * for execution.  A scheduler consists of

cpukit/include/rtems/score/schedulerpriority.h

@@ -34,7 +34,8 @@ extern "C" {
  *
  * @ingroup RTEMSScoreScheduler
  *
- * @brief Deterministic Priority Scheduler
+ * @brief This group contains the Deterministic Priority Scheduler
+ *   implementation.
  *
  * @{
  */

cpukit/include/rtems/score/schedulerpriorityaffinitysmp.h

@@ -34,7 +34,8 @@ extern "C" {
  *
  * @ingroup RTEMSScoreSchedulerPrioritySMP
  *
- * @brief Deterministic Priority Affinity SMP Scheduler
+ * @brief This group contains the Deterministic Priority Affinity SMP Scheduler
+ *   implementation.
  *
  * This is an extension of the Deterministic Priority SMP Scheduler. which
  * is an implementation of the global fixed priority scheduler (G-FP). 

cpukit/include/rtems/score/schedulerprioritysmp.h

@@ -36,7 +36,7 @@ extern "C" {
  *
  * @ingroup RTEMSScoreSchedulerSMP
  *
- * @brief Deterministic Priority SMP Scheduler
+ * @brief This group contains the Deterministic Priority SMP Scheduler implementation.
  *
  * This is an implementation of the global fixed priority scheduler (G-FP).  It
  * uses one ready chain per priority to ensure constant time insert operations.

cpukit/include/rtems/score/schedulersimple.h

@@ -32,7 +32,7 @@ extern "C" {
  *
  * @ingroup RTEMSScoreScheduler
  *
- * @brief Simple Priority Scheduler
+ * @brief This group contains the Simple Priority Scheduler implementation.
  *
  * @{
  */

cpukit/include/rtems/score/schedulersimplesmp.h

@@ -32,7 +32,7 @@ extern "C" {
  *
  * @ingroup RTEMSScoreSchedulerSMP
  *
- * @brief Simple Priority SMP Scheduler
+ * @brief This group contains the Simple Priority SMP Scheduler implementation.
  *
  * The Simple Priority SMP Scheduler allocates a processor for the processor
  * count highest priority ready threads.  The thread priority and position in

cpukit/include/rtems/score/schedulersmp.h

@@ -35,7 +35,7 @@ extern "C" {
  *
  * @ingroup RTEMSScoreScheduler
  *
- * @brief SMP Scheduler
+ * @brief This group contains the SMP Scheduler implementation.
  *
  * @{
  */

cpukit/include/rtems/score/schedulerstrongapa.h

@@ -36,7 +36,7 @@ extern "C" {
  *
  * @ingroup RTEMSScoreSchedulerSMP
  *
- * @brief Strong APA Scheduler
+ * @brief This group contains the Strong APA Scheduler implementation.
  *
  * This is an implementation of the global fixed priority scheduler (G-FP).  It
  * uses one ready chain per priority to ensure constant time insert operations.

cpukit/include/rtems/score/smp.h

@@ -29,9 +29,7 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief SMP Support
- *
- * This defines the interface of the SuperCore SMP support.
+ * @brief This group contains the implementation to support SMP systems.
  *
  * @{
  */

cpukit/include/rtems/score/smpbarrier.h

@@ -35,8 +35,10 @@ extern "C" {
  *
  * @ingroup RTEMSScore
  *
- * @brief The SMP barrier provides barrier synchronization for SMP systems at
- * the lowest level.
+ * @brief This group contains the SMP barrier implementation.
+ *
+ * The SMP barrier provides barrier synchronization for SMP systems at the
+ * lowest level.
  *
  * The SMP barrier is implemented as a sense barrier, see also Herlihy and
  * Shavit, "The Art of Multiprocessor Programming", 17.3 Sense-Reversing

cpukit/include/rtems/score/smpimpl.h

@@ -1,7 +1,7 @@
 /**
  * @file
  *
- * @ingroup RTEMSScoreSMPImpl
+ * @ingroup RTEMSScoreSMP
  *
  * @brief SuperCore SMP Implementation
  */

cpukit/include/rtems/score/smplock.h

@@ -27,8 +27,9 @@
  *
  * @ingroup RTEMSScore
  *
- * @brief The SMP lock provides mutual exclusion for SMP systems at the lowest
- * level.
+ * @brief This group contains the SMP lock implementation.
+ *
+ * The SMP lock provides mutual exclusion in SMP systems at the lowest level.
  *
  * The SMP lock is implemented as a ticket lock.  This provides fairness in
  * case of concurrent lock attempts.