focus-flow/Codex Documentation/Completed Plans/V1_BLOCK_28_Project-wide_Documentation_Sweep.md

V1 Block 28 — Project‑wide Documentation Sweep

Purpose: JavaDoc-style commenting.

Note for Codex: Follow tasks exactly; avoid exploratory calls when tasks specify names/files/tests.

Chunk 28.1 — Documentation sweep

Recommended level: HIGH

Status: Complete on 2026-06-26.

Tasks

1. Enable dart doc in CI; fail build if undocumented public members.
2. Add docs to all public symbols across packages using triple‑slash style.
3. Document build scripts and CI YAML with comments at top describing purpose.

Acceptance criteria

1. dart doc generates site without warnings.
2. CI passes doc coverage gate.

Completed implementation

1. Added tool/check_docs.dart to generate docs for every package with a lib/ directory under doc/api/packages/.
2. The doc gate fails on any dart doc warning or nonzero doc generation exit.
3. Added doc generation to scripts/test.dart, so scripts/test.sh and CI run the docs gate.
4. Updated CI artifact upload to include generated docs under doc/api/.
5. Added .gitignore entry for generated doc/api/ output.
6. Fixed unresolved documentation references in scheduler_core, scheduler_export, and scheduler_export_json.
7. Added top-of-file purpose comments to scripts/dev.dart, scripts/test.dart, scripts/build.dart, tool/check_coverage.dart, tool/check_docs.dart, and .github/workflows/ci.yml.

Verification

1. dart run tool/check_docs.dart: passed; docs generated for all public-library packages with 0 warnings and 0 errors.
2. dart analyze: passed, no issues found.
3. scripts/test.sh: passed.
4. Coverage result in final gate: 83.27% package lib/ line coverage, above the 80% threshold.

---