<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html lang="en" style="--code-editor-font: var(--default-mono-font, "GitLab Mono"), JetBrains Mono, Menlo, DejaVu Sans Mono, Liberation Mono, Consolas, Ubuntu Mono, Courier New, andale mono, lucida console, monospace;">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
<title>
GitLab
</title>
<style data-premailer="ignore" type="text/css">
a { color: #1068bf; }
</style>
<style>img {
max-width: 100%; height: auto;
}
body {
font-size: .875rem;
}
body {
-webkit-text-shadow: hsla(0,0%,100%,.01) 0 0 1px;
}
body {
font-family: "GitLab Sans",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans",Ubuntu,Cantarell,"Helvetica Neue",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji"; font-size: inherit;
}
</style>
</head>
<body style="font-size: inherit; -webkit-text-shadow: hsla(0,0%,100%,.01) 0 0 1px; font-family: "GitLab Sans",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Noto Sans",Ubuntu,Cantarell,"Helvetica Neue",sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol","Noto Color Emoji";">
<div class="content">
<p class="details" style="font-style: italic; color: #626168;">
Issue created by <a href="https://gitlab.rtems.org/sebhub">Sebastian Huber</a>: <a href="https://gitlab.rtems.org/rtems/rtos/rtems/-/work_items/5717">#5717</a>
</p>
<div class="md" style="position: relative; z-index: 1; color: #3a383f; word-wrap: break-word;">
<h2 id="user-content-problem" dir="auto" style="margin-top: 0px; margin-bottom: 10px;" align="initial">Problem<a href="#problem" aria-label="Link to heading 'Problem'" data-heading-content="Problem" class="anchor" style="margin-top: 0px;"></a>
</h2>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">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.</p>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">Most files of cpukit do not appear in that tree. The 2053 files in scope
carry these defects:</p>
<table dir="auto" style="border-spacing: 0; text-align: initial; color: #3a383f; width: auto; border-collapse: collapse; margin: 16px 0; border-width: 0;">
<thead style="margin-top: 0px;">
<tr style="margin-top: 0px;">
<th style="line-height: 1.25rem; color: #18171d; margin-top: 0px; padding: 10px 16px; border-color: #dcdcde; border-style: solid; border-width: 1px 1px 0;" valign="top">Defect</th>
<th align="right" style="line-height: 1.25rem; color: #18171d; padding: 10px 16px; border-color: #dcdcde; border-style: solid; border-width: 1px 1px 0;" valign="top">Files</th>
</tr>
</thead>
<tbody>
<tr style="margin-top: 0px;">
<td style="line-height: 1.25rem; margin-top: 0px; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">No Doxygen file block</td>
<td align="right" style="line-height: 1.25rem; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">291</td>
</tr>
<tr>
<td style="line-height: 1.25rem; margin-top: 0px; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">No group which reaches an anchor group</td>
<td align="right" style="line-height: 1.25rem; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">706</td>
</tr>
<tr>
<td style="line-height: 1.25rem; margin-top: 0px; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">A brief which does not name the content of the file</td>
<td align="right" style="line-height: 1.25rem; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">1279</td>
</tr>
</tbody>
</table>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">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.</p>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">Doxygen reports 311 warnings of the kind <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0px; font-weight: inherit; overflow-wrap: break-word; white-space: break-spaces; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; word-break: keep-all; padding: 0.125rem 0.25rem;">Found non-existing group</code> for
cpukit outside the imported code. It drops the group and builds the page.
No build fails, so the defect survives.</p>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">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.</p>
<h2 id="user-content-motivation" dir="auto" style="margin-top: 20px; margin-bottom: 10px;" align="initial">Motivation<a href="#motivation" aria-label="Link to heading 'Motivation'" data-heading-content="Motivation" class="anchor" style="margin-top: 0px;"></a>
</h2>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">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.</p>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">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.</p>
<h2 id="user-content-acceptance-criteria" dir="auto" style="margin-top: 20px; margin-bottom: 10px;" align="initial">Acceptance criteria<a href="#acceptance-criteria" aria-label="Link to heading 'Acceptance criteria'" data-heading-content="Acceptance criteria" class="anchor" style="margin-top: 0px;"></a>
</h2>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">Every file of cpukit outside the paths below meets four rules:</p>
<ol dir="auto" style="text-align: initial; margin: 0px 0px 1rem; padding: 0;">
<li style="margin-top: 0px; line-height: 1.6em; margin-left: 25px; padding-left: 3px;">The file carries a Doxygen block with <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0px; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">@file</code>.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">The block names a group with <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0px; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">@ingroup</code>.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">The group reaches RTEMSAPI, RTEMSImpl, RTEMSDeviceDrivers or
RTEMSBSPsShared.</li>
<li style="line-height: 1.6em; margin-left: 25px; padding-left: 3px;">A header brief starts with "This header file provides". A source brief
starts with "This source file contains".</li>
</ol>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">Two sets of files keep a form of their own. The files <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0px; font-weight: inherit; overflow-wrap: break-word; white-space: break-spaces; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; word-break: keep-all; padding: 0.125rem 0.25rem;">malloc.h</code>,
<code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-weight: inherit; overflow-wrap: break-word; white-space: break-spaces; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; word-break: keep-all; padding: 0.125rem 0.25rem;">score/todimpl.h</code> and <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-weight: inherit; overflow-wrap: break-word; white-space: break-spaces; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; word-break: keep-all; padding: 0.125rem 0.25rem;">printk_plugin.c</code> name two groups each, because each
of them holds the content of two components. The 23 headers under
<code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-weight: inherit; overflow-wrap: break-word; white-space: break-spaces; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; word-break: keep-all; padding: 0.125rem 0.25rem;">confdefs/</code> and the header <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-weight: inherit; overflow-wrap: break-word; white-space: break-spaces; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; word-break: keep-all; padding: 0.125rem 0.25rem;">confdefs.h</code> keep their brief. It starts with
"This header file evaluates", which is what those headers do.</p>
<p dir="auto" style="color: #3a383f; margin: 0px 0px 1rem;" align="initial">Doxygen reports no warning of the kind <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0px; font-weight: inherit; overflow-wrap: break-word; white-space: break-spaces; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; word-break: keep-all; padding: 0.125rem 0.25rem;">Found non-existing group</code> for cpukit
outside those paths.</p>
<h2 id="user-content-out-of-scope" dir="auto" style="margin-top: 20px; margin-bottom: 10px;" align="initial">Out of scope<a href="#out-of-scope" aria-label="Link to heading 'Out of scope'" data-heading-content="Out of scope" class="anchor" style="margin-top: 0px;"></a>
</h2>
<table dir="auto" style="border-spacing: 0; text-align: initial; color: #3a383f; width: auto; border-collapse: collapse; margin: 16px 0; border-width: 0;">
<thead style="margin-top: 0px;">
<tr style="margin-top: 0px;">
<th style="line-height: 1.25rem; color: #18171d; margin-top: 0px; padding: 10px 16px; border-color: #dcdcde; border-style: solid; border-width: 1px 1px 0;" valign="top">Path</th>
<th style="line-height: 1.25rem; color: #18171d; padding: 10px 16px; border-color: #dcdcde; border-style: solid; border-width: 1px 1px 0;" valign="top">Reason</th>
</tr>
</thead>
<tbody>
<tr style="margin-top: 0px;">
<td style="line-height: 1.25rem; margin-top: 0px; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top"><code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0px; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">cpukit/contrib/</code></td>
<td style="line-height: 1.25rem; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">imported code, the next import overwrites a local change</td>
</tr>
<tr>
<td style="line-height: 1.25rem; margin-top: 0px; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">
<code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0px; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">cpukit/dtc/</code>, <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">cpukit/libcrypt/</code>, <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">cpukit/libfs/src/jffs2/</code>, <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">cpukit/libmd/</code>, <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">cpukit/libstdthreads/</code>
</td>
<td style="line-height: 1.25rem; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">imported code</td>
</tr>
<tr>
<td style="line-height: 1.25rem; margin-top: 0px; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">
<code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; margin-top: 0px; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">bsps/</code> and <code style="font-size: 90%; color: #18171d; word-wrap: break-word; background-color: #ececef; border-radius: .25rem; font-family: "GitLab Mono", "JetBrains Mono", "Menlo", "DejaVu Sans Mono", "Liberation Mono", "Consolas", "Ubuntu Mono", "Courier New", "andale mono", "lucida console", monospace; font-variant-ligatures: none; white-space: pre-wrap; overflow-wrap: break-word; word-break: keep-all; padding: 0.125rem 0.25rem;">testsuites/</code>
</td>
<td style="line-height: 1.25rem; padding: 10px 16px; border: 1px solid #dcdcde;" valign="top">266 group warnings of their own, which need a work item of their own</td>
</tr>
</tbody>
</table>
<p dir="auto" style="color: #3a383f; margin: 0px;" align="initial">This work item description was created with the help of Claude Code.</p>
</div>
</div>
<div class="footer" style="margin-top: 10px;">
<p style="font-size: small; color: #626168;">
—
<br>
<a href="https://gitlab.rtems.org/rtems/rtos/rtems/-/work_items/5717">View it on GitLab</a>.
<br>
You're receiving this email because of your account on <a target="_blank" rel="noopener noreferrer" href="https://gitlab.rtems.org">gitlab.rtems.org</a>. <a href="https://gitlab.rtems.org/-/sent_notifications/5-f42awnui2n1atvkl5a7noc3pb-1d/unsubscribe" target="_blank" rel="noopener noreferrer">Unsubscribe</a> from this thread · <a href="https://gitlab.rtems.org/-/profile/notifications" target="_blank" rel="noopener noreferrer" class="mng-notif-link">Manage all notifications</a> · <a href="https://gitlab.rtems.org/help" target="_blank" rel="noopener noreferrer" class="help-link">Help</a>
<span style="color: transparent; font-size: 0; display: none; overflow: hidden; opacity: 0; width: 0; height: 0; max-width: 0; max-height: 0;">
Notification message regarding https://gitlab.rtems.org/rtems/rtos/rtems/-/work_items/5717 at 1787115285
</span>
<script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","action":{"@type":"ViewAction","name":"View Work item","url":"https://gitlab.rtems.org/rtems/rtos/rtems/-/work_items/5717"}}</script>
</p>
</div>
</body>
</html>