# Documentation health

1087 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 | 190 of 1087 | A doc comment in the source. Nothing generated improves on this. |
| Generated, with citations | 104 of 1087 | Points at specific `file:line` ranges you can open and check. |
| Generated, without citations | 261 of 1087 | Often right, but nothing anchors it. Treat as a starting point. |
| Not described | 532 of 1087 | The page shows structure only — signature, members, references. |

**294 of 1087 descriptions can be checked against source** — 190 because the author wrote them next to the code, 104 because the generator cited the lines it read. The rest are shown, and marked, for what they are.

## 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.

- [`packages/microservices`](subsystem-packages-microservices) — 227 of 399 undescribed
- [`packages/common`](subsystem-packages-common) — 131 of 322 undescribed
- [`packages/core`](subsystem-packages-core) — 120 of 253 undescribed
- [`packages/websockets`](subsystem-packages-websockets) — 23 of 57 undescribed
- [`packages/platform-express`](subsystem-packages-platform-express) — 14 of 22 undescribed
- [`packages/platform-fastify`](subsystem-packages-platform-fastify) — 9 of 14 undescribed
- [`packages/testing`](subsystem-packages-testing) — 2 of 11 undescribed