docs/ names library symbols in prose and in fenced examples, and nothing
asserts that any of them exist. Three instances of the same defect were found by
hand on 2026-08-10, two of them by review rather than by a gate:
docs/platforms/windows/setup.md named SolidSyslogWindowsHostname and
SolidSyslogWindowsProcessId; the symbols were _Get-suffixed.
docs/platforms/posix/setup.md carried the identical pair for Posix.
docs/platforms/freertos/setup.md named the component where the function was
meant.
All three predated the branch that found them, all three sat on pages that build
green under mkdocs build --strict, and all three would give an integrator who
copied the page an undefined-symbol error.
scripts/check_platform_docs.py already parses every platform header and every
platform page, and already runs in the docs-build lane, so the assertion has a
home: a SolidSyslog… token in a page resolves to a symbol declared in a public
header, or to a file that exists, or it fails. The awkward part is the exception
list rather than the check — docs/NAMING.md names old spellings deliberately as
counter-examples, and prose sometimes names a class rather than a function.
Deliberately not for 0.1.0: David's call, 2026-08-10 — the checking is not
needed for the beta, and the remaining platform triages are the higher-value use
of the time. Raised so the finding survives.
Related: nothing compiles the fenced C examples in docs/ either, and two
defects have been found in examples by reading alone. That check is larger; this
one is strictly cheaper and catches a different class.
docs/names library symbols in prose and in fenced examples, and nothingasserts that any of them exist. Three instances of the same defect were found by
hand on 2026-08-10, two of them by review rather than by a gate:
docs/platforms/windows/setup.mdnamedSolidSyslogWindowsHostnameandSolidSyslogWindowsProcessId; the symbols were_Get-suffixed.docs/platforms/posix/setup.mdcarried the identical pair for Posix.docs/platforms/freertos/setup.mdnamed the component where the function wasmeant.
All three predated the branch that found them, all three sat on pages that build
green under
mkdocs build --strict, and all three would give an integrator whocopied the page an undefined-symbol error.
scripts/check_platform_docs.pyalready parses every platform header and everyplatform page, and already runs in the
docs-buildlane, so the assertion has ahome: a
SolidSyslog…token in a page resolves to a symbol declared in a publicheader, or to a file that exists, or it fails. The awkward part is the exception
list rather than the check —
docs/NAMING.mdnames old spellings deliberately ascounter-examples, and prose sometimes names a class rather than a function.
Deliberately not for 0.1.0: David's call, 2026-08-10 — the checking is not
needed for the beta, and the remaining platform triages are the higher-value use
of the time. Raised so the finding survives.
Related: nothing compiles the fenced C examples in
docs/either, and twodefects have been found in examples by reading alone. That check is larger; this
one is strictly cheaper and catches a different class.