score: Canonicalize Doxygen @file comments

Use common phrases for the file brief descriptions.

Update #3706.

cpukit/include/rtems/score/address.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScoreAddress
  *
- * @brief Information Required to Manipulate Physical Addresses
- *
- * This include file contains the information required to manipulate
- * physical addresses.
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreAddress.
  */
 
 /*

cpukit/include/rtems/score/apimutex.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreAPIMutex
  *
- * @brief API Mutex Handler API
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreAPIMutex.
  */
 
 /*

cpukit/include/rtems/score/assert.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreAssert
  *
- * @brief Information for the Assert Handler
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreAssert.
  */
 
 /*

cpukit/include/rtems/score/atomic.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreAtomic
  *
- * @brief Atomic Operations API
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreAtomic.
  */
 
 /*

cpukit/include/rtems/score/chain.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreChain
  *
- * @brief Chain Handler API
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreChain which are used by the implementation and the API.
  */
 
 /*

cpukit/include/rtems/score/chainimpl.h

@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Chain Handler API
- *
  * @ingroup RTEMSScoreChain
+ *
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreChain which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/context.h

@@ -3,9 +3,8 @@
  *
  * @ingroup RTEMSScoreContext
  *
- * @brief Information About Each Thread's Context
- *
- * This include file contains all information about each thread's context.
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreContext.
  */
 
 /*

cpukit/include/rtems/score/copyrt.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSSuperCoreCopyright
  *
- * @brief Copyright Notice for RTEMS
- *
- * This include file contains the copyright notice for RTEMS
- * which is included in every binary copy of the executive.
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreCopyright.
  */
 
 /*

cpukit/include/rtems/score/corebarrier.h

@@ -3,10 +3,9 @@
  *
  * @ingroup RTEMSScoreBarrier
  *
- * @brief Constants and Structures Associated with the Barrier Handler
- *
- * This include file contains all the constants and structures associated
- * with the Barrier Handler.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreBarrier which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*

cpukit/include/rtems/score/corebarrierimpl.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScoreBarrier
  *
- * @brief Inlined Routines Associated with the SuperCore Barrier
- *
- * This include file contains all of the inlined routines associated
- * with the SuperCore barrier.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreBarrier which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/coremsg.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScoreMessageQueue
  *
- * @brief Constants and Structures Associated with the Message Queue Handler.
- *
- * This include file contains all the constants and structures associated
- * with the Message queue Handler.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMessageQueue which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/coremsgbuffer.h

@@ -5,8 +5,9 @@
  *
  * @ingroup RTEMSScoreMessageQueue
  *
- * @brief This header file defines the buffer data structure used by the
- *   Message Queue Handler.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMessageQueue which are used by the implementation, the
+ *   @ref RTEMSImplApplConfig, and the API.
  */
 
 /*

cpukit/include/rtems/score/coremsgimpl.h

@@ -3,10 +3,9 @@
  *
  * @ingroup RTEMSScoreMessageQueue
  *
- * @brief Inlined Routines in the Core Message Handler
- *
- * This include file contains the static inline implementation of all
- * inlined routines in the Core Message Handler.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMessageQueue which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*

cpukit/include/rtems/score/coremutex.h

@@ -3,12 +3,9 @@
  *
  * @ingroup RTEMSScoreMutex
  *
- * @brief CORE Mutex API
- *
- * This include file contains all the constants and structures associated with
- * the Mutex Handler.  A mutex is an enhanced version of the standard Dijkstra
- * binary semaphore used to provide synchronization and mutual exclusion
- * capabilities.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMutex which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*
@@ -43,7 +40,9 @@ extern "C" {
  * @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.
+ * Mutex services used in all of the APIs supported by RTEMS.  A mutex is an
+ * enhanced version of the standard Dijkstra binary semaphore used to provide
+ * synchronization and mutual exclusion capabilities.
  *
  * @{
  */

cpukit/include/rtems/score/coremuteximpl.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreMutex
  *
- * @brief CORE Mutex Implementation
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMutex which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/corerwlockimpl.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScoreRWLock
  *
- * @brief Inlined Routines Associated with the SuperCore RWLock
- *
- * This include file contains all of the inlined routines associated
- * with the SuperCore RWLock.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreRWLock which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/coresem.h

@@ -3,12 +3,9 @@
  *
  * @ingroup RTEMSScoreSemaphore
  *
- * @brief Data Associated with the Counting Semaphore Handler
- *
- * This include file contains all the constants and structures associated
- * with the Counting Semaphore Handler.  A counting semaphore is the
- * standard Dijkstra binary semaphore used to provide synchronization
- * and mutual exclusion capabilities.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreSemaphore which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*

cpukit/include/rtems/score/coresemimpl.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScoreSemaphore
  *
- * @brief Inlined Routines Associated with the SuperCore Semaphore
- *
- * This include file contains all of the inlined routines associated
- * with the SuperCore semaphore.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreSemaphore which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/cpustdatomic.h

@@ -1,7 +1,8 @@
 /**
  * @file
  * 
- * @brief Atomic Operations CPU API
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreAtomicCPU.
  */
 
 /*

cpukit/include/rtems/score/freechain.h

@@ -3,8 +3,11 @@
  *
  * @ingroup RTEMSScoreFreechain
  *
- * @brief Freechain Handler API
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreFreechain which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
+
 /*
  * Copyright (c) 2013 Gedare Bloom.
  *

cpukit/include/rtems/score/freechainimpl.h

@@ -3,8 +3,10 @@
  *
  * @ingroup RTEMSScoreFreechain
  *
- * @brief Freechain Handler API
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreBarrier which are only used by the implementation.
  */
+
 /*
  * Copyright (c) 2013 Gedare Bloom.
  *

cpukit/include/rtems/score/heap.h

@@ -3,7 +3,9 @@
  *
  * @ingroup RTEMSScoreHeap
  *
- * @brief Heap Handler API
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreHeap which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*

cpukit/include/rtems/score/heapimpl.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreHeap
  *
- * @brief Heap Handler Implementation
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreBarrier which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/heapinfo.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreHeap
  *
- * @brief Heap Handler Information API
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreBarrier which are used by the implementation and the API.
  */
 
 /*

cpukit/include/rtems/score/interr.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScoreIntErr
  *
- * @brief Constants and Prototypes Related to the Internal Error Handler
- *
- * This include file contains constants and prototypes related
- * to the Internal Error Handler.
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreIntErr.
  */
 
 /*

cpukit/include/rtems/score/io.h

@@ -1,3 +1,12 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSScoreIO
+ *
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreIO.
+ */
+
 /*
  * Copyright (c) 2017 embedded brains GmbH.  All rights reserved.
  *

cpukit/include/rtems/score/isr.h

@@ -3,12 +3,8 @@
  *
  * @ingroup RTEMSScoreISR
  *
- * @brief Data Related to the Management of Processor Interrupt Levels
- *
- * This include file contains all the constants and structures associated
- * with the management of processor interrupt levels.  This handler
- * supports interrupt critical sections, vectoring of user interrupt
- * handlers, nesting of interrupts, and manipulating interrupt levels.
+ * @brief This header file provides the main interfaces of the
+ *   @ref RTEMSScoreISR.
  */
 
 /*
@@ -33,7 +29,9 @@
  * @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.
+ * ISR services used in all of the APIs supported by RTEMS.  This handler
+ * supports interrupt critical sections, vectoring of user interrupt handlers,
+ * nesting of interrupts, and manipulating interrupt levels.
  *
  * The ::_ISR_Nest_level variable is maintained by @ref RTEMSScorePerCPU.
  *

cpukit/include/rtems/score/isrlevel.h

@@ -3,10 +3,10 @@
  *
  * @ingroup RTEMSScoreISR
  *
- * @brief ISR Level Type
+ * @brief This header file provides the ::ISR_Level related interfaces of the
+ *   @ref RTEMSScoreISR.
  *
- * This include file defines the ISR Level type.  It exists to
- * simplify include dependencies.  It is part of the ISR Handler.
+ * This header file exists to simplify include dependencies.
  */
 
 /*

cpukit/include/rtems/score/isrlock.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreISRLocks
  *
- * @brief ISR Locks
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreISRLocks.
  */
 
 /*

cpukit/include/rtems/score/memory.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreMemory
  *
- * @brief Memory Handler API
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreMemory.
  */
 
 /*

cpukit/include/rtems/score/mpci.h

@@ -3,7 +3,9 @@
  *
  * @ingroup RTEMSScoreMPCI
  *
- * @brief MPCI Layer API
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMPCI which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*

cpukit/include/rtems/score/mpciimpl.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreMPCI
  *
- * @brief MPCI Layer Implementation
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMPCI which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/mppkt.h

@@ -3,13 +3,8 @@
  *
  * @ingroup RTEMSScoreMPPacket
  *
- * @brief Specification for the Packet Handler
- *
- * This package is the specification for the Packet Handler.
- * This handler defines the basic packet and provides
- * mechanisms to utilize packets based on this prefix.
- * Packets are the fundamental basis for messages passed between
- * nodes in an MP system.
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreMPPacket.
  */
 
 /*
@@ -42,7 +37,9 @@ extern "C" {
  *
  * This handler encapsulates the primary definition of MPCI packets.  This
  * handler defines the part of the packet that is common to all remote
- * operations.
+ * operations.  It defines the basic packet and provides mechanisms to utilize
+ * packets based on this prefix.  Packets are the fundamental basis for
+ * messages passed between nodes in an MP system.
  *
  * @{
  */

cpukit/include/rtems/score/mrsp.h

@@ -3,7 +3,9 @@
  *
  * @ingroup RTEMSScoreMRSP
  *
- * @brief Definitions for Multiprocessor Resource Sharing Protocol (MrsP).
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMRSP which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*

cpukit/include/rtems/score/mrspimpl.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreMRSP
  *
- * @brief Definitions for Multiprocessor Resource Sharing Protocol (MrsP) Implementation.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreMRSP which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/muteximpl.h

@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @ingroup RTEMSScoreAPIMutex
+ * @ingroup RTEMSScoreSyslockMutex
  *
- * @brief Structures for the implementation of mutexes.
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreSyslockMutex.
  */
 
 /*
@@ -25,16 +26,22 @@
 
 #include <rtems/score/threadqimpl.h>
 
-/**
- * @addtogroup RTEMSScoreAPIMutex
- *
- * @{
- */
-
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @defgroup RTEMSScoreSyslockMutex System Lock Mutex Support
+ *
+ * @ingroup RTEMSScore
+ *
+ * @brief The System Lock Mutex Support helps to implement directives which use
+ *   data structures compatible with the data structures defined by the Newlib
+ *   provided <sys/lock.h> header file.
+ *
+ * @{
+ */
+
 typedef struct {
   Thread_queue_Syslock_queue Queue;
 } Mutex_Control;
@@ -44,10 +51,10 @@ typedef struct {
   unsigned int nest_level;
 } Mutex_recursive_Control;
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
 
-/** @} */
-
 #endif /* _RTEMS_SCORE_MUTEXIMPL_H */

cpukit/include/rtems/score/object.h

@@ -3,11 +3,9 @@
  *
  * @ingroup RTEMSScoreObject
  *
- * @brief Constants and Structures Associated with the Object Handler
- *
- * This include file contains all the constants and structures associated
- * with the Object Handler.  This Handler provides mechanisms which
- * can be used to initialize and manipulate all objects which have ids.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreObject which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*
@@ -55,6 +53,9 @@ extern "C" {
  *
  * @brief This group contains the Object Handler implementation.
  *
+ * This handler provides mechanisms which can be used to initialize and
+ * manipulate all objects which have identifiers.
+ *
  * @{
  */
 

cpukit/include/rtems/score/objectimpl.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScoreObject
  *
- * @brief Inlined Routines in the Object Handler
- *
- * This include file contains the static inline implementation of all
- * of the inlined routines in the Object Handler.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreObject which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/objectmp.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScoreObjectMP
  *
- * @brief Data Associated with the Manipulation of Global RTEMS Objects
- *
- * This include file contains all the constants and structures associated
- * with the manipulation of Global RTEMS Objects.
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreObjectMP.
  */
 
 /*

cpukit/include/rtems/score/onceimpl.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreOnce
  *
- * @brief Once API
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreOnce.
  */
 
 /*

cpukit/include/rtems/score/percpu.h

@@ -1,8 +1,10 @@
 /**
- *  @file
+ * @file
  *
- *  This include file defines the per CPU information required
- *  by RTEMS.
+ * @ingroup RTEMSScorePerCPU
+ *
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScorePerCPU.
  */
 
 /*

cpukit/include/rtems/score/percpudata.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScorePerCPUData
  *
- * @brief This header file provides the Flexible Per-CPU Data API.
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScorePerCPUData.
  */
 
 /*

cpukit/include/rtems/score/priority.h

@@ -3,7 +3,9 @@
  *
  * @ingroup RTEMSScorePriority
  *
- * @brief Priority Handler API
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScorePriority which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*

cpukit/include/rtems/score/prioritybitmap.h

@@ -3,10 +3,9 @@
  *
  * @ingroup RTEMSScorePriorityBitmap
  *
- * @brief Manipulation Routines for the Bitmap Priority Queue Implementation
- *
- * This include file contains all thread priority manipulation routines for
- * the bit map priority queue implementation.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScorePriorityBitmap which are used by the implementation and the
+ *   @ref RTEMSImplApplConfig.
  */
 
 /*

cpukit/include/rtems/score/prioritybitmapimpl.h

@@ -3,10 +3,8 @@
  *
  * @ingroup RTEMSScorePriorityBitmap
  *
- * @brief Inlined Routines in the Priority Handler Bit Map Implementation
- *
- * This file contains the static inline implementation of all inlined
- * routines in the Priority Handler bit map implementation
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScorePriorityBitmap which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/priorityimpl.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScorePriority
  *
- * @brief Priority Handler API Implementation.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScorePriority which are only used by the implementation.
  */
 
 /*

cpukit/include/rtems/score/processormask.h

@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Processor Mask API
- *
  * @ingroup RTEMSScoreProcessorMask
+ *
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreProcessorMask.
  */
 
 /*

cpukit/include/rtems/score/profiling.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreProfiling
  *
- * @brief Profiling Support API
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreProfiling.
  */
 
 /*

cpukit/include/rtems/score/protectedheap.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSScoreProtHeap
  *
- * @brief Protected Heap Handler API
+ * @brief This header file provides the interfaces of the
+ *   @ref RTEMSScoreProtHeap.
  */
 
 /*

cpukit/include/rtems/score/rbtree.h

@@ -3,10 +3,9 @@
  *
  * @ingroup RTEMSScoreRBTree
  *
- * @brief Constants and Structures Associated with the Red-Black Tree Handler
- *
- * This include file contains all the constants and structures associated
- * with the Red-Black Tree Handler.
+ * @brief This header file provides interfaces of the
+ *   @ref RTEMSScoreRBTree which are used by the implementation, the
+ *   @ref RTEMSImplApplConfig, and the API.
  */
 
 /*