cpukit: Write the dynamic linker Doxygen briefs

The briefs of the dynamic linker named a topic, not the content of the
file.  Three of them named the wrong topic.  The files rtl-obj.c and
rtl-find-file.c both said "RTEMS Run-Time Linker Error".  The header
rtl-rap.h said "RTEMS Run-Time Linker ELF Headers".

Write every brief in the style of the tree.  Do the same for the four
Doxygen support headers and for the remaining single files in aio,
endian, memory, mqueue, pci, libgnat, ftpd and libdebugger.

Put @file, @ingroup and @brief in this order in every block.

The header appl-config.h keeps its brief.  A generator produces that
file.

Updates #5717.

Assisted-by: Claude:claude-opus-5 claude-code
Signed-off-by: Sebastian Huber <sebastian.huber@embedded-brains.de>

cpukit/doxygen/build.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplDoxygen
  *
- * @brief This header file defines build system related Doxygen items.
+ * @brief This header file provides the Doxygen definitions of the build
+ *   system.
  */
 
 /*

cpukit/doxygen/hash-algorithms.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplDoxygen
  *
- * @brief This header file contains Doxygen items related to hash algorithms.
+ * @brief This header file provides the Doxygen definitions of the hash
+ *   algorithms.
  */
 
 /*

cpukit/doxygen/mainpage.h

@@ -5,8 +5,8 @@
  *
  * @ingroup RTEMSImplDoxygen
  *
- * @brief This file exists to provide a top level description of RTEMS for
- *   Doxygen.
+ * @brief This header file provides the main page of the generated
+ *   documentation.
  */
 
 /*

cpukit/doxygen/top-level-groups.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplDoxygen
  *
- * @brief This header file defines high level Doxygen groups.
+ * @brief This header file provides the high level Doxygen group
+ *   definitions.
  */
 
 /*

cpukit/ftpd/ftpd.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplFTPD
  *
- * @brief
+ * @brief This source file contains the implementation of the FTP daemon.
  */
 
 /* FIXME: 1. Parse command is a hack.  We can do better.

cpukit/include/aio.h

@@ -4,9 +4,10 @@
  * @file
  *
  * @ingroup RTEMSImplPOSIXAio
- * 
- * @brief POSIX Asynchronous I/O Support
- * 
+ *
+ * @brief This header file provides the interfaces of the POSIX asynchronous
+ *   input and output support.
+ *
  * This file contains the definitions related to POSIX I/O.
  */
 

cpukit/include/endian.h

@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
  * @ingroup RTEMSImplFreeBSDKernel
  *
- *  @brief
+ * @brief This header file provides the byte order definitions used by
+ *   ported components.
  */
 
 /*

cpukit/include/memory.h

@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
  * @ingroup RTEMSImplFreeBSDKernel
  *
- *  @brief Dummy include file for FreeBSD routines
+ * @brief This header file provides the memory function declarations used by
+ *   ported components.
  */
 
 /*

cpukit/include/mqueue.h

@@ -5,10 +5,11 @@
  *
  * @ingroup RTEMSImplPOSIXMessageQueue
  *
- * @brief POSIX Message Queues
- * 
+ * @brief This header file provides the interfaces of the POSIX message
+ *   queues.
+ *
  * This file contains the definitions related to POSIX Message Queues.
- * 
+ *
  * The structure of the routines is identical to that of POSIX
  * Message_queues to leave the option of having unnamed message
  * queues at a future date.  They are currently not part of the

cpukit/include/pci.h

@@ -5,11 +5,10 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brief PCI Library
+ * @brief This header file provides the interfaces of the PCI library.
  *
  * Defines in this file was taken from FreeBSD and auto-generated
  * pci_ids.h reused from RTEMS.
- *
  */
 
 /*

cpukit/libdebugger/rtems-debugger-microblaze.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplDebugger
  *
- * @brief MicroBlaze libdebugger implementation
+ * @brief This source file contains the MicroBlaze target support of the
+ *   debugger server.
  */
 
 /*

cpukit/libdl/dlfcn-shell.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor Dynamic Loading API Shell Support.
+ * @brief This source file contains the shell commands of the dynamic
+ *   linker.
  *
  * Shell command wrappers for the Dynamic Loading API.
  */

cpukit/libdl/dlfcn.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS POSIX Dynamic Module Loading Interface.
+ * @brief This source file contains the implementation of dlopen(),
+ *   dlclose(), dlsym(), dlerror() and dlinfo().
  *
  * This is the POSIX interface to run-time loading of code into RTEMS.
  */

cpukit/libdl/rap-shell.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Application Loader.
+ * @brief This source file contains the shell command of the RAP loader.
  *
  * Shell command wrappers for the RTEMS Application loader.
  */

cpukit/libdl/rap.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplLibDLRAP
  *
- * @brief RTEMS Application Loader
+ * @brief This source file contains the implementation of the RAP loader.
  *
  * This is the RAP implementation.
  */

cpukit/libdl/rtl-alloc-heap.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Allocator for the standard heap.
+ * @brief This source file contains the heap allocator of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl-alloc-heap.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Allocator for the standard heap.
+ * @brief This header file provides the heap allocator interfaces of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-allocator.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Allocator
+ * @brief This source file contains the allocator of the dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-archive.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Archive
+ * @brief This source file contains the archive support of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl-bit-alloc.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor Bit Allocator
+ * @brief This source file contains the bit allocator of the dynamic linker.
  *
  * A configurable allocator for small peices of memory where embedding
  * control blocks into the memory are not viable. The amount of memory

cpukit/libdl/rtl-bit-alloc.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Bit Allocator Header
+ * @brief This header file provides the bit allocator interfaces of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-chain-iterator.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor Chain Iterator
+ * @brief This source file contains the chain iterator of the dynamic
+ *   linker.
  *
  * A means of executing an iterator on a chain.
  */

cpukit/libdl/rtl-chain-iterator.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Chain Iterator.
+ * @brief This header file provides the chain iterator interfaces of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-debugger.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Module Loading Debugger Interface.
+ * @brief This source file contains the debugger interface of the dynamic
+ *   linker.
  *
  * Inspection of run-time linkers in NetBSD and Android show a common type of
  * structure that is used to interface to GDB. The NetBSD definition of this

cpukit/libdl/rtl-elf.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor
+ * @brief This source file contains the ELF support of the dynamic linker.
  *
  * This is the RTL implementation.
  */

cpukit/libdl/rtl-elf.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker ELF Headers
+ * @brief This header file provides the ELF interfaces of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl-error.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Error
+ * @brief This source file contains the error support of the dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-error.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Error
+ * @brief This header file provides the error interfaces of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl-find-file.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Error
+ * @brief This source file contains the implementation of
+ *   rtems_rtl_find_file().
  */
 
 /*

cpukit/libdl/rtl-find-file.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Object Support.
+ * @brief This header file provides the file lookup interfaces of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-mdreloc-lm32.c

@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
  * @ingroup RTEMSImplLibDL
  *
- *  @brief
+ * @brief This source file contains the LatticeMico32 relocation support of
+ *   the dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-mdreloc-mips.c

@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
  * @ingroup RTEMSImplLibDL
  *
- *  @brief
+ * @brief This source file contains the MIPS relocation support of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-mdreloc-moxie.c

@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
  * @ingroup RTEMSImplLibDL
  *
- *  @brief
+ * @brief This source file contains the Moxie relocation support of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-mdreloc-powerpc.c

@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
  * @ingroup RTEMSImplLibDL
  *
- *  @brief
+ * @brief This source file contains the PowerPC relocation support of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-obj-cache.c

@@ -5,8 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Object File cache buffers a section of the
- *        object file in a buffer to localise read performance.
+ * @brief This source file contains the object file cache of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl-obj-comp.c

@@ -5,8 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Object Compression manages a compress
- *        stream of data.
+ * @brief This source file contains the object file decompressor of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-obj.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Error
+ * @brief This source file contains the object file support of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl-rap.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor
+ * @brief This source file contains the RAP file support of the dynamic
+ *   linker.
  *
  * This is the RAP format loader support..
  */

cpukit/libdl/rtl-rap.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker ELF Headers
+ * @brief This header file provides the RAP file interfaces of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl-shell.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor Shell Commands
+ * @brief This source file contains the shell commands of the dynamic
+ *   linker.
  *
  * A simple RTL command to aid using the RTL.
  */

cpukit/libdl/rtl-string.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker String managment.
+ * @brief This source file contains the implementation of
+ *   rtems_rtl_strdup().
  */
 
 /*

cpukit/libdl/rtl-string.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker String managment.
+ * @brief This header file provides the string interfaces of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl-sym.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Object File Symbol Table.
+ * @brief This source file contains the symbol table of the dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-tls.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor Thread Local Storage
+ * @brief This source file contains the thread-local storage support of the
+ *   dynamic linker.
  *
  * TLS support the RTL.
  */

cpukit/libdl/rtl-tls.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor Thread Local Storage
+ * @brief This header file provides the thread-local storage interfaces of
+ *   the dynamic linker.
  *
  * TLS support the RTL.
  */

cpukit/libdl/rtl-trace.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor Trace
+ * @brief This source file contains the trace support of the dynamic linker.
  *
  * A configurable tracer for the RTL. See the header file for the enable and
  * disable.

cpukit/libdl/rtl-trampoline.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Object File Trampoline Relocations Table.
+ * @brief This header file provides the trampoline interfaces of the dynamic
+ *   linker.
  *
  * Cache relocation records that could result in a trampoline. The unresolved
  * symbol table holds variable the symbol name (length string) and the object

cpukit/libdl/rtl-unresolved.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Object File Unresolved Relocations Table.
+ * @brief This source file contains the unresolved symbol table of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-unwind-dw2.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor
+ * @brief This source file contains the DWARF 2 unwind support of the
+ *   dynamic linker.
  *
  * This is the RTL implementation.
  */

cpukit/libdl/rtl-unwind-dw2.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Unwind DWARF  Support.
+ * @brief This header file provides the DWARF 2 unwind interfaces of the
+ *   dynamic linker.
  */
 
 /*

cpukit/libdl/rtl-unwind.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Linker Unwind Support.
+ * @brief This header file provides the unwind interfaces of the dynamic
+ *   linker.
  */
 
 /*

cpukit/libdl/rtl.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplLibDL
  *
- * @brief RTEMS Run-Time Link Editor
+ * @brief This source file contains the implementation of the dynamic
+ *   linker.
  *
  * This is the RTL implementation.
  */

cpukit/libgnat/adasupp.c

@@ -1,11 +1,12 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
- *  @file
+ * @file
  *
  * @ingroup RTEMSImplGnat
  *
- *  @brief ada supplmental functions
+ * @brief This source file contains the support functions of the Ada
+ *   run-time.
  */
 
 /*