[davidt315]

Publishes a Doxygen-generated C/C++ API reference on the docs website, under a new API navbar tab.

• Doxyfile at docs/developing/Doxyfile (public headers only, warnings fail the build).
• npm run docs:api, run in the docs CI workflow, which now also triggers on header changes.
• AGENTS.md: API docs go in header docstrings, not new pages under docs/.
• Fixes a missing @param in backend.hpp and replaces a stale IMachineBackend sketch in machine_ros_2_lifecycle_node.md with a pointer to the header.

The Doxyfile INPUT list and the workflow paths: filter must stay in sync (both carry a comment saying so).

Testing

npm run docs:api and npm run build / npm start

NOTE: The CI Failure on docs is intentional and resolved in PR 2 of this Stack. It's failing because not everything is documented. PR 2 Documents the undocumented code. DO NOT MERGE ALONE

[graphify-labs]

Graphify reviewed this change.

No issues found by static checks — no coupling regressions or blocking issues in the code graph. That is not the same as safe to merge: see what was not checked.

Not checked: tests were not run; no formal proof of the changed code.

---

Graphify review — findings

Adds a Doxygen-generated C/C++ API reference, published under a new API navbar tab. docs/developing/Doxyfile reads the public headers (pstop_c, ros2/protective_stop_machine, common) and writes to the gitignored website/static/api. The docs workflow now installs doxygen and graphviz and runs npm run docs:api before the site build, with WARN_AS_ERROR so any Doxygen warning fails CI. The header paths also now trigger the workflow on push to main. Removes the hand-written IMachineBackend code block from the lifecycle node design doc, which now points at backend.hpp and the generated reference. backend.hpp also gains a missing @param timing on configure, which Doxygen would otherwise warn on. Adds an API Reference developer page on building and writing the docs, plus an AGENTS.md section saying API docs live in header comments, not in pages under docs/.

No blocking issues surfaced.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 111 functions depend on the 111 functions this change touches.

Health — grade A; no new coupling hotspots.

Verification — 111 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 111 function(s) in the blast radius were not formally verified this run

[claude]

Code review found no issues

No high-confidence issues detected in this change.

Still open from earlier reviews (1):

• Unresolved: 1 minor or pre-existing.

[claude]

🔴 Flipping WARN_IF_UNDOCUMENTED to YES at Doxyfile:37 (WARN_AS_ERROR stays YES at :38) now breaks the new docs:api CI build, well beyond the one mismatch already fixed in this PR. Many public members across the scanned headers have zero recognized Doxygen comment, e.g. most RemoteInfo/RelayInfo/MachineSnapshot/MachineTiming fields plus state() in ros2/protective_stop_machine/include/protective_stop_machine/backend.hpp:31-77 — each now triggers a warned-as-error 'member not documented'. Under the previously reviewed value (NO) these were silently tolerated. Fix: fully document every public member these headers expose before turning WARN_IF_UNDOCUMENTED on, or keep it NO until that doc sweep across backend.hpp is complete.

Why this was flagged

docs/developing/Doxyfile:37 changed WARN_IF_UNDOCUMENTED from NO (the value the last posted review saw) to YES, while WARN_AS_ERROR stays YES at :38. Doxygen then errors on any public entity lacking a /** or /// style comment. pstop_c/pstop/include/pstop/pstop_remote_data.h:88 (pstop_remote_num_stopped) has no doc comment at all. ros2/protective_stop_machine/include/protective_stop_machine/backend.hpp has undocumented struct fields (RemoteInfo::stop_only:31, reply_age_ms/loop_rtt_ms/disco_rtt_ms/rebonds:32-35, RelayInfo::run/relay_stop/fault_a/fault_b/mismatch:42-46, MachineSnapshot fields:53-59, MachineTiming fields:75-77) and the state() method:61. Running npm run docs:api / the docs.yml step will now fail on these, whereas it passed when WARN_IF_UNDOCUMENTED was NO.

Verification: Doxyfile sets WARN_IF_UNDOCUMENTED=YES (:37) and WARN_AS_ERROR=YES (:38); docs.yml runs docs:api on every pull_request. backend.hpp's MachineSnapshot (:49-50) has undocumented members reachable(:53), running(:54) and state()(:61), each a warned-as-error 'not documented'. The base branch (d683161) has no such step, so this job is new and failing. The PR's @ param fix does not test this path.

[davidt315]

PR 2 in this stack addresses the CI failure by documenting the undocumented members

[iliabaranov]

looks good, no concerns