Skip to content

chore: assert that a symbol named in the docs exists #740

Description

@DavidCozens

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    choreMaintenance, tooling, and infrastructuredocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions