[davidt315]

Adds doxygen comments to the previously undocumented members to fix the docs build failures

[graphify-labs]

Graphify reviewed this change.

Code graph out of date: Health delta baseline: last indexed commit d683161, 2 commit(s) behind this PR's base. Impact and hotspot numbers below may be wrong.

No verdict: the code graph is out of date. Static checks found no blocking issues, but they compared against an outdated graph. The next push after the repository re-indexes gets a full review.

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

---

Graphify review — findings

Adds Doxygen comments across the C headers (pstop_c, the shared pstop_aux_channel.h role schema) and the ROS 2 protective_stop_machine headers, covering backend, announcer, fleet check-in, hardware and software backends, JSON parser and bridge node. Long file-header prose blocks, such as the MachineAnnouncer overview and the role-schema notes, are condensed into @file or @brief docs. Flips WARN_IF_UNDOCUMENTED to YES in the Doxyfile, so with WARN_AS_ERROR on, any new undocumented public symbol now fails the docs build. No runtime behaviour changes.

No blocking issues surfaced. 1 lower-confidence candidate did not survive cross-model review.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 249 functions depend on the 204 functions this change touches.

Health — grade A; 10 existing hotspot(s) in the area this change touches (pre-existing, not introduced here):

• dcs_support_init() — 2 callers, 31 callees (high)
• sess_bond_step() — 1 callers, 8 callees (medium)
• page_state() — 0 callers, 41 callees (high)
• main() — 0 callers, 34 callees (high)
• comparator_task() — 0 callers, 26 callees (high)
• comparator_task() — 0 callers, 12 callees (high)
• core_task() — 0 callers, 9 callees (medium)
• TEST() — 0 callers, 9 callees (medium)
• …and 2 more

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

Health delta baseline: last indexed commit d683161, 2 commit(s) behind this PR's base.

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: 247 function(s) in the blast radius were not formally verified this run

[claude]

LGTM — this is a mechanical, comment-only documentation change with no logic/behavior modifications.

What was reviewed: the Doxygen /////** */ comments added across the C/ROS headers (struct fields, enums, callbacks) all state non-obvious info (units, ownership, invariants) rather than restating names. Checked that the narrative file-header blocks removed from announce.hpp/fleet_checkin.hpp were condensed into class-level @ brief comments rather than dropped outright. Independently verified the WARN_IF_UNDOCUMENTED=YES flip in Doxyfile — other untouched headers (error.h, config.h, checksum.h, etc.) have zero doc comments at all, so with EXTRACT_ALL=NO they're simply excluded from the doc set rather than triggering warnings; no struct/enum touched in this diff is left partially documented.

Extended reasoning...

Doc-only PR converting plain comments to Doxygen /////** */ across 13 C/C++ headers plus flipping Doxyfile's WARN_IF_UNDOCUMENTED to YES; no code logic, auth, or security-sensitive paths touched. Verified by reading every changed-file diff that only comments were added/reworded (no behavior change), that newly-documented structs have all fields documented (no partial-doc gaps that would break the WARN_AS_ERROR build), and that other untouched headers remain fully undocumented (zero doc comments), which Doxygen with EXTRACT_ALL=NO silently excludes rather than warns about — so the flagged build-break concern does not apply. No open third-party objections were visible in the available timeline metadata.

This review covers commit c65bc86, which is no longer the latest commit on this pull request; later commits are not covered by it.

[iliabaranov]

related to the other PR in this stack, also seems fine