Issue created by Sebastian Huber: https://gitlab.rtems.org/rtems/rtos/rtems/-/work_items/5717
## Problem The generated documentation presents RTEMS as a tree of groups. The group RTEMSAPI holds the interfaces which an application uses. The group RTEMSImpl holds the implementation. A reader starts at one of these groups and walks down to a file. Most files of cpukit do not appear in that tree. The 2053 files in scope carry these defects: | Defect | Files | | --- | ---: | | No Doxygen file block | 291 | | No group which reaches an anchor group | 706 | | A brief which does not name the content of the file | 1279 | A file reaches no anchor for one of four reasons. The file names no group. The file names a group which no file defines. The file names a group which hangs under no anchor. The file carries no block at all. Doxygen reports 311 warnings of the kind `Found non-existing group` for cpukit outside the imported code. It drops the group and builds the page. No build fails, so the defect survives. The brief is the one line which a group page shows next to a file name. The brief "x86_64 Dependent Source" names a topic. It does not tell a reader what the file holds. Some briefs name a function which the file does not define. ## Motivation A reader who walks down from RTEMSAPI or RTEMSImpl misses 706 files of cpukit. Doxygen documents each file, but no group page links to it. The reader must know the file name in advance. The group tree then serves no purpose. The two anchors also carry a promise. A header under RTEMSAPI is an interface for an application. A header under RTEMSImpl is not. A file in the wrong anchor invites an application writer to call an interface which RTEMS does not support. ## Acceptance criteria Every file of cpukit outside the paths below meets four rules: 1. The file carries a Doxygen block with `@file`. 2. The block names a group with `@ingroup`. 3. The group reaches RTEMSAPI, RTEMSImpl, RTEMSDeviceDrivers or RTEMSBSPsShared. 4. A header brief starts with "This header file provides". A source brief starts with "This source file contains". Two sets of files keep a form of their own. The files `malloc.h`, `score/todimpl.h` and `printk_plugin.c` name two groups each, because each of them holds the content of two components. The 23 headers under `confdefs/` and the header `confdefs.h` keep their brief. It starts with "This header file evaluates", which is what those headers do. Doxygen reports no warning of the kind `Found non-existing group` for cpukit outside those paths. ## Out of scope | Path | Reason | | --- | --- | | `cpukit/contrib/` | imported code, the next import overwrites a local change | | `cpukit/dtc/`, `cpukit/libcrypt/`, `cpukit/libfs/src/jffs2/`, `cpukit/libmd/`, `cpukit/libstdthreads/` | imported code | | `bsps/` and `testsuites/` | 266 group warnings of their own, which need a work item of their own | This work item description was created with the help of Claude Code. -- View it on GitLab: https://gitlab.rtems.org/rtems/rtos/rtems/-/work_items/5717 You're receiving this email because of your account on gitlab.rtems.org. Unsubscribe from this thread: https://gitlab.rtems.org/-/sent_notifications/5-f42awnui2n1atvkl5a7noc3pb-1d/unsubscribe | Manage all notifications: https://gitlab.rtems.org/-/profile/notifications | Help: https://gitlab.rtems.org/help
_______________________________________________ bugs mailing list [email protected] http://lists.rtems.org/mailman/listinfo/bugs
