# 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.

---