cpukit: Write the driver and PCI Doxygen briefs

The briefs of the block device drivers and the PCI headers named a
topic, not the content of the file.  Five libblock files carried the
same brief "Media implementation.".  Four more carried "RAM disk block
device implementation.".

Write every brief in the style of the tree.  A source brief starts with
"This source file contains" and names the functions the file defines
where there are at most three.  A header brief starts with "This header
file provides".  Put @file, @ingroup and @brief in this order.

The CAN and CAN FD stack keeps its briefs.  Its contributors write them
in a style of their own.

Updates #5717.

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

cpukit/dev/i2c/i2c-bus.c

@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Inter-Integrated Circuit (I2C) Bus Implementation
- *
  * @ingroup I2CBus
+ *
+ * @brief This source file contains the implementation of the I2C bus
+ *   driver.
  */
 
 /*

cpukit/dev/i2c/i2c-dev.c

@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Inter-Integrated Circuit (I2C) Bus Implementation
- *
  * @ingroup I2CDevice
+ *
+ * @brief This source file contains the implementation of the I2C device
+ *   driver.
  */
 
 /*

cpukit/dev/spi/spi-bus.c

@@ -1,9 +1,10 @@
 /**
  * @file
  *
- * @brief Serial Peripheral Interface (SPI) Bus Implementation
- *
  * @ingroup SPI
+ *
+ * @brief This source file contains the implementation of the SPI bus
+ *   driver.
  */
 
 /*

cpukit/doxygen.h

@@ -3,7 +3,8 @@
  *
  * @ingroup RTEMSImplDoxygen
  *
- * @brief This header file defines some Doxygen groups.
+ * @brief This header file provides the Doxygen group definitions which no
+ *   other header provides.
  */
 
 /**

cpukit/include/dev/flash/flashdev.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSGenericFlashAPI
  *
- * @brief Generic Flash API
+ * @brief This header file provides the interfaces of the generic flash
+ *   device driver.
  */
 
 /*

cpukit/include/dev/i2c/i2c.h

@@ -3,9 +3,9 @@
 /**
  * @file
  *
- * @brief Inter-Integrated Circuit (I2C) Driver API
- *
  * @ingroup I2C
+ *
+ * @brief This header file provides the interfaces of the I2C bus driver.
  */
 
 /*

cpukit/include/dev/io/iodev.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSGenericIOSpaceAPI
  *
- * @brief Generic IO Device API
+ * @brief This header file provides the interfaces of the generic I/O device
+ *   driver.
  */
 
 /*

cpukit/include/dev/spi/spi.h

@@ -3,9 +3,9 @@
 /**
  * @file
  *
- * @brief Serial Peripheral Interface (SPI) Driver API
- *
  * @ingroup SPI
+ *
+ * @brief This header file provides the interfaces of the SPI bus driver.
  */
 
 /*

cpukit/include/drvmgr/drvmgr.h

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplDriverManager
  *
- * @brief Driver Manager Interface.
+ * @brief This header file provides the interfaces of the driver manager.
  */
 
 /*

cpukit/include/drvmgr/drvmgr_confdefs.h

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplDriverManager
  *
- * @brief Driver Manager Configuration file.
+ * @brief This header file provides the configuration of the driver manager.
  */
 
 /*

cpukit/include/drvmgr/drvmgr_list.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplDriverManager
  *
- * @brief Linked list help functions used by driver manager.
+ * @brief This header file provides the list interfaces of the driver
+ *   manager.
  */
 
 /*

cpukit/include/drvmgr/pci_bus.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplDriverManager
  *
- * @brief PCI bus driver Interface.
+ * @brief This header file provides the interfaces of the PCI bus driver of
+ *   the driver manager.
  */
 
 /*

cpukit/include/linux/i2c-dev.h

@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @brief RTEMS Port of Linux I2C Device API
- *
  * @ingroup I2CLinux
+ *
+ * @brief This header file provides the Linux I2C device interfaces ported
+ *   to RTEMS.
  */
 
 /*

cpukit/include/linux/i2c.h

@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @brief RTEMS Port of Linux I2C API
- *
  * @ingroup I2CLinux
+ *
+ * @brief This header file provides the Linux I2C interfaces ported to
+ *   RTEMS.
  */
 
 /*

cpukit/include/linux/spi/spidev.h

@@ -3,9 +3,10 @@
 /**
  * @file
  *
- * @brief RTEMS Port of Linux SPI API
- *
  * @ingroup SPILinux
+ *
+ * @brief This header file provides the Linux SPI device interfaces ported
+ *   to RTEMS.
  */
 
 /*

cpukit/include/pci/access.h

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brief PCI Access Methods
+ * @brief This header file provides the PCI access interfaces.
  *
  * Routines to access PCI memory/configuration space and other PCI related
  * functions the PCI Library provides.

cpukit/include/pci/cfg.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brief PCI Configuration Library
+ * @brief This header file provides the PCI configuration library
+ *   interfaces.
  */
 
 /*

cpukit/include/pci/cfg_auto.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brief PCI Auto Configuration Library
+ * @brief This header file provides the automatic PCI configuration
+ *   interfaces.
  */
 
 /*

cpukit/include/pci/cfg_peripheral.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brie PCI Peripheral Configuration Libraryf
+ * @brief This header file provides the peripheral PCI configuration
+ *   interfaces.
  */
 
 /*

cpukit/include/pci/cfg_read.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brief PCI Read Configuration Library
+ * @brief This header file provides the interfaces which read the PCI
+ *   configuration.
  *
  * Read current config where bootloader/BIOS has setup.
  */

cpukit/include/pci/cfg_static.h

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brief Static PCI Auto Configuration Library
+ * @brief This header file provides the static PCI configuration interfaces.
  */
 
 /*

cpukit/include/pci/ids_extra.h

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brief RTEMS local PCI data base
+ * @brief This header file provides the PCI identifiers which RTEMS adds to
+ *   the database.
  */
 
 /*

cpukit/include/pci/irq.h

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSImplPCI
  *
- * @brief PCI IRQ Library
+ * @brief This header file provides the PCI interrupt interfaces.
  */
 
 /*

cpukit/libblock/src/bdbuf.c

@@ -3,7 +3,8 @@
  *
  * @ingroup rtems_bdbuf
  *
- * Block device buffer management.
+ * @brief This source file contains the implementation of the block device
+ *   buffer cache.
  */
 
 /*

cpukit/libblock/src/bdpart-create.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_bdpart
  *
- * @brief Manage Partitions of a Disk Device
+ * @brief This source file contains the implementation of
+ *   rtems_bdpart_create().
  */
 
 /*

cpukit/libblock/src/bdpart-dump.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_bdpart
  *
- * @brief Prints the Partition Table @a Partitions with @a Count Partitions
+ * @brief This source file contains the implementation of
+ *   rtems_bdpart_dump().
  */
 
 /*

cpukit/libblock/src/bdpart-read.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_bdpart
  *
- * @brief Block Device Partition Management
+ * @brief This source file contains the implementation which reads the
+ *   partition table of a disk device.
  */
 
 /*

cpukit/libblock/src/bdpart-register.c

@@ -5,7 +5,9 @@
  *
  * @ingroup rtems_bdpart
  *
- * @brief Block Device Partition Management
+ * @brief This source file contains the implementation of
+ *   rtems_bdpart_register(), rtems_bdpart_register_from_disk() and
+ *   rtems_bdpart_unregister().
  */
 
 /*

cpukit/libblock/src/bdpart-sort.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_bdpart
  *
- * @brief Block Device Partition Management
+ * @brief This source file contains the implementation of
+ *   rtems_bdpart_sort().
  */
 
 /*

cpukit/libblock/src/bdpart-write.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_bdpart
  *
- * @brief Block Device Partition Management
+ * @brief This source file contains the implementation of
+ *   rtems_bdpart_write().
  */
 
 /*

cpukit/libblock/src/blkdev-blkstats.c

@@ -5,7 +5,7 @@
  *
  * @ingroup rtems_blkdev
  *
- * @brief Block Device Statistics Command
+ * @brief This source file contains the implementation of rtems_blkstats().
  */
 
 /*

cpukit/libblock/src/blkdev-imfs.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_blkdev
  *
- * @brief Block Device IMFS
+ * @brief This source file contains the implementation of
+ *   rtems_blkdev_create() and rtems_blkdev_create_partition().
  */
 
 /*

cpukit/libblock/src/blkdev-ioctl.c

@@ -3,7 +3,8 @@
  *
  * @ingroup rtems_blkdev
  *
- * @brief Common IO Control Primitive
+ * @brief This source file contains the implementation of
+ *   rtems_blkdev_ioctl().
  */
 
 /*

cpukit/libblock/src/blkdev-ops.c

@@ -5,7 +5,7 @@
  *
  * @ingroup rtems_blkdev
  *
- * @brief Block device management.
+ * @brief This source file contains the block device operations tables.
  */
 
 /*

cpukit/libblock/src/blkdev-print-stats.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_blkdev
  *
- * @brief Prints the Block Device Statistics
+ * @brief This source file contains the implementation of
+ *   rtems_blkdev_print_stats().
  */
 
 /*

cpukit/libblock/src/blkdev.c

@@ -3,7 +3,8 @@
  *
  * @ingroup rtems_blkdev
  *
- * @brief Block Device Management
+ * @brief This source file contains the generic read and write handlers of
+ *   the block device driver.
  */
 
 /*

cpukit/libblock/src/diskdevs-init.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_disk
  *
- * @brief Block Device Disk Management Initialize
+ * @brief This source file contains the implementation of
+ *   rtems_disk_init_phys() and rtems_disk_init_log().
  */
 
 /*

cpukit/libblock/src/diskdevs.c

@@ -3,7 +3,8 @@
  *
  * @ingroup rtems_disk
  *
- * @brief Block device disk management implementation.
+ * @brief This source file contains the implementation of the disk device
+ *   management.
  */
 
 /*

cpukit/libblock/src/flashdisk.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSFDisk
  *
- * @brief Flash Disk Block Device Implementation
+ * @brief This source file contains the implementation of
+ *   rtems_fdisk_initialize().
  */
 
 /*

cpukit/libblock/src/ide_part_table.c

@@ -5,7 +5,9 @@
  *
  * @ingroup rtems_libblock
  *
- * @brief Library supporting "MS-DOS-style" Partition Table
+ * @brief This source file contains the implementation of
+ *   rtems_ide_part_table_free(), rtems_ide_part_table_get() and
+ *   rtems_ide_part_table_initialize().
  */
 
 /*

cpukit/libblock/src/media-desc.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSDeviceMedia
  *
- * @brief Media implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_media_event_description() and rtems_media_state_description().
  */
 
 /*

cpukit/libblock/src/media-dev-ident.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSDeviceMedia
  *
- * @brief Media implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_media_get_device_identifier().
  */
 
 /*

cpukit/libblock/src/media-path.c

@@ -5,7 +5,9 @@
  *
  * @ingroup RTEMSDeviceMedia
  *
- * @brief Media implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_media_create_path(), rtems_media_replace_prefix() and
+ *   rtems_media_append_minor().
  */
 
 /*

cpukit/libblock/src/media-server.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSDeviceMedia
  *
- * @brief Media implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_media_server_initialize() and rtems_media_server_post_event().
  */
 
 /*

cpukit/libblock/src/media.c

@@ -5,7 +5,9 @@
  *
  * @ingroup RTEMSDeviceMedia
  *
- * @brief Media implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_media_listener_add(), rtems_media_listener_remove() and
+ *   rtems_media_post_event().
  */
 
 /*

cpukit/libblock/src/nvdisk-sram.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_libblock
  *
- * @brief Provide SRAM support for the NV Disk
+ * @brief This source file contains the SRAM support of the non-volatile
+ *   disk driver.
  */
 
 /*

cpukit/libblock/src/nvdisk.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_libblock
  *
- * @brief Non-Volatile Disk Block Device Implementation
+ * @brief This source file contains the implementation of
+ *   rtems_nvdisk_initialize().
  */
 
 /*

cpukit/libblock/src/ramdisk-config.c

@@ -3,7 +3,8 @@
  *
  * @ingroup rtems_ramdisk
  *
- * @brief RAM disk block device implementation.
+ * @brief This source file contains the implementation of
+ *   ramdisk_initialize().
  */
 
 /*

cpukit/libblock/src/ramdisk-driver.c

@@ -3,7 +3,7 @@
  *
  * @ingroup rtems_ramdisk
  *
- * @brief RAM disk block device implementation.
+ * @brief This source file contains the implementation of ramdisk_ioctl().
  */
 
 /*

cpukit/libblock/src/ramdisk-init.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_ramdisk
  *
- * @brief RAM disk block device implementation.
+ * @brief This source file contains the implementation of ramdisk_allocate()
+ *   and ramdisk_free().
  */
 
 /*

cpukit/libblock/src/ramdisk-register.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_ramdisk
  *
- * @brief RAM disk block device implementation.
+ * @brief This source file contains the implementation of
+ *   ramdisk_register().
  */
 
 /*

cpukit/libblock/src/show_bdbuf.c

@@ -5,7 +5,8 @@
  *
  * @ingroup rtems_bdpart
  *
- * @brief Enable the Monitor to Show bdbuf Information
+ * @brief This source file contains the monitor support which shows the
+ *   block device buffer cache.
  *
  * This module inspects the bdbuf data structures,
  * assuming they are static, but in fact they are used very

cpukit/libblock/src/sparse-disk.c

@@ -5,7 +5,9 @@
  *
  * @ingroup rtems_sparse_disk
  *
- * @brief Sparse disk block device implementation.
+ * @brief This source file contains the implementation of
+ *   rtems_sparse_disk_free(), rtems_sparse_disk_create_and_register() and
+ *   rtems_sparse_disk_register().
  */
 
 /*

cpukit/libtest/testrun.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSTest
  *
- * @brief This source file provides the implementation of rtems_test_run().
+ * @brief This source file contains the implementation of rtems_test_run().
  */
 
 /*

cpukit/score/src/exceptionmapping.c

@@ -5,7 +5,8 @@
  *
  * @ingroup RTEMSScoreException
  *
- * @brief AArch64 machine exception to POSIX signal mapping.
+ * @brief This source file contains the implementation of
+ *   _Exception_Raise_signal().
  */
 
 /*

cpukit/score/src/hash.c

@@ -5,7 +5,7 @@
  *
  * @ingroup RTEMSScoreHash
  *
- * @brief This source file the implementation of _Hash_Finalize().
+ * @brief This source file contains the implementation of _Hash_Finalize().
  */
 
 /*