9008 symbols have a reference page in this documentation. This page says how each of them came to be described, because "documented" covers four situations a reader should not have to treat alike.
Where the descriptions come from
| Symbols | What it means for a reader | |
|---|---|---|
| Written by the author | 28 of 9008 | A doc comment in the source. Nothing generated improves on this. |
| Generated, with citations | 0 of 9008 | Points at specific file:line ranges you can open and check. |
| Generated, without citations | 516 of 9008 | Often right, but nothing anchors it. Treat as a starting point. |
| Not described | 8464 of 9008 | The page shows structure only — signature, members, references. |
28 of 9008 descriptions can be checked against source — 28 because the author wrote them next to the code, 0 because the generator cited the lines it read. The rest are shown, and marked, for what they are.
343 symbols carried a description that is the same sentence repeated across many symbols — a README or manifest description copied per package. Those are not counted as authored: a sentence pasted per package is presence, not authorship.
Why there is no coverage percentage
A percentage counts whether a comment exists, so the cheapest way to raise it is to add empty ones. SonarQube withdrew its comment-density metric over this; studies of "covered" API documentation classify 43–51% of it as carrying no information; and a missing-comment warning has been measured producing 1,774 junk comments in a single codebase. The counts above cannot be moved that way — a doc comment that only restates the symbol name is not counted as one.
Where the gaps are
Undescribed symbols by the part of the system they sit in — worst first, so the next unit of documentation effort has an address. This is the table to bring to planning.
| Area | Undescribed | Of | Share |
|---|---|---|---|
Pams | 6578 | 7016 | 94% |
Frontend/src/app | 1573 | 1661 | 95% |
Pams/Web/portal/pams-web/src/app | 164 | 166 | 99% |
Outlook_plugin/src/calendar | 60 | 76 | 79% |
Outlook_plugin/src/attachement | 23 | 23 | 100% |
Outlook_plugin/src/auth | 22 | 22 | 100% |
Outlook_plugin/src/activity | 17 | 17 | 100% |
Outlook_plugin | 11 | 11 | 100% |
Outlook_plugin/src/contacts | 9 | 9 | 100% |
Frontend/src | 7 | 7 | 100% |
What can be checked
A claim on these pages is anchored when it points at something a reader can open: a file:line range in the source, or a [census] tag naming the arithmetic behind a number. Anything else is prose you would have to take on trust. These counts say which is which. They do not say the anchored claims are right — only that they can be checked.
| Count | What it means | |
|---|---|---|
| Pages read by this audit | 9021 [census] | Every page in the set as it stood before this section was written. This section's own claims are not counted below. |
| Pages carrying an anchored claim | 1 of 9021 [census] | The page points at source or at a census at least once. |
| Anchored claims | 46 [census] | One per file:line reference and per census tag. Brackets inside code samples are code, and are not counted. |
| … pointing at source | 30 of 46 [census] | A path and a line you can open. |
| … pointing at a census | 16 of 46 [census] | A number computed before anything was written. |
Whether those citations land in files that exist was NOT CHECKED for this build: the audit was given no way to look a path up. The count above is of citations made, not of citations verified — and reporting them as sound on that basis would be the invention this page exists to catch.
Every count in this section and the two below is arithmetic over these pages, redone on each build; [census] marks a figure read from that arithmetic rather than written by hand.
Where the docs and the code disagree
One lint reads every page for a single pattern: a sentence stating runtime behaviour — what listens, what validates, what retries — whose only evidence is a prose document. A README saying the server listens on a port is testimony ABOUT the code, not the behaviour itself, and a sentence citing it for the behaviour has quietly turned one into the other. The honest forms either cite the source that listens, or keep the attribution in the sentence.
No page states runtime behaviour on the authority of a prose document alone. That is an absence of the pattern rather than proof the pages and the code agree: the lint reads verbs and file extensions, and it misses what it was not taught to see.
What we have not written yet
The evidence census lists, for each part of this repository, the reader-topics that part's contents warrant: a part holding database models owes its readers a data model however few models it holds. This section holds that list against the headings the pages for each part actually carry.
1 of 24 reader-topics, across 11 parts of this repository, have no page carrying a heading that answers for them [census].
| Part | Topics no heading answers for | Pages for this part |
|---|---|---|
azure-dns-migration | wiring | 1 [census] |
A topic counts as written when any page for its part carries a heading naming it — "Fields" answers for a data model, "Endpoint" for an API surface, "Dependencies" for wiring. The match is deliberately loose in that direction: a topic covered under a heading nobody predicted must not be reported as missing, so the error this makes is silence, never a false accusation of absence.
3 pages name no source path [census], so they were matched to no part and can cover no topic above — the pages about this documentation itself are among them.
Was this page helpful?