feat(doc): fail the check on a missing doc comment #384

Merged

argus merged 1 commit from loop/317-doc-check-fails-on-missing into main 2026-10-18 22:50:10 +00:00

Conversation 1 Commits 1 Files changed 9 +88 -51

orion commented 2026-10-18 22:03:29 +00:00

Collaborator

Copy link

Closes #317

What

A public construct that the standard asks a doc comment of and that has none is now a problem of torb doc --check, like a broken link: one line per construct (file:line: Type.member has no doc comment), sorted with the other problems, counted in the closing N problems, exit code 1. The separate N of M ... have no doc comment summary and reportMissing are dropped. The tier A gate doc --check --no-run std in tools/gates.sh therefore enforces the rule; no new gate.

• compiler/src/reference/model.trb: Reference.undocumentedLines becomes missingDocumentationProblems (a DocumentationProblem per construct).
• compiler/src/reference/command.trb: runDoc adds them to the problems; usage text and module comment updated.
• Tests in compiler/tests/reference.test.trb: an undocumented required field fails with file and line, a fully documented package has no problem, and the member of an extend ... with Trait without a doc comment passes.
• docs/tooling/torb-doc.md ("Missing doc comments", help text, example output), its copy in skills/, compiler/CONTRIBUTING.md, the tools/gates.sh comments and docs/ROADMAP.md (the strict check moves from open work to built, 2026-10-19).

No syntax, native, driver flag or looked-up std name changes, so the seed is untouched and uses no new language feature.

Test

Not run locally (no bootstrap or gates outside CI, orion/infra#947). Forge CI of this PR runs sh tools/gates.sh a, including doc --check --no-run std (must report 0 missing on main, #316 reported 0), docs skill --check, docs check docs and format --check. tools/check-commits.sh origin/main HEAD is clean.

Closes #317 ## What A public construct that the standard asks a doc comment of and that has none is now a problem of `torb doc --check`, like a broken link: one line per construct (`file:line: Type.member has no doc comment`), sorted with the other problems, counted in the closing `N problems`, exit code 1. The separate `N of M ... have no doc comment` summary and `reportMissing` are dropped. The tier A gate `doc --check --no-run std` in `tools/gates.sh` therefore enforces the rule; no new gate. - `compiler/src/reference/model.trb`: `Reference.undocumentedLines` becomes `missingDocumentationProblems` (a `DocumentationProblem` per construct). - `compiler/src/reference/command.trb`: `runDoc` adds them to the problems; usage text and module comment updated. - Tests in `compiler/tests/reference.test.trb`: an undocumented required field fails with file and line, a fully documented package has no problem, and the member of an `extend ... with Trait` without a doc comment passes. - `docs/tooling/torb-doc.md` ("Missing doc comments", help text, example output), its copy in `skills/`, `compiler/CONTRIBUTING.md`, the `tools/gates.sh` comments and `docs/ROADMAP.md` (the strict check moves from open work to built, 2026-10-19). No syntax, native, driver flag or looked-up std name changes, so the seed is untouched and uses no new language feature. ## Test Not run locally (no bootstrap or gates outside CI, orion/infra#947). Forge CI of this PR runs `sh tools/gates.sh a`, including `doc --check --no-run std` (must report 0 missing on `main`, #316 reported 0), `docs skill --check`, `docs check docs` and `format --check`. `tools/check-commits.sh origin/main HEAD` is clean.

orion added 1 commit 2026-10-18 22:03:29 +00:00

feat(doc): fail the check on a missing doc comment ... c4693dee02

A public construct that the standard asks a doc comment of and that has none is now a problem of torb doc --check, one line per construct with its file and line, counted in the closing problems line. The tier A gate doc --check --no-run std enforces it. Docs, skills and the ROADMAP are updated.

orion force-pushed loop/317-doc-check-fails-on-missing from c4693dee02 to 7b63923ad5 2026-10-18 22:04:20 +00:00 Compare

orion force-pushed loop/317-doc-check-fails-on-missing from 7b63923ad5 to 381e6b507b 2026-10-18 22:11:54 +00:00 Compare

orion force-pushed loop/317-doc-check-fails-on-missing from 381e6b507b to 482c0b97a4 2026-10-18 22:19:33 +00:00 Compare

orion force-pushed loop/317-doc-check-fails-on-missing from 482c0b97a4 to 41b6874e60 2026-10-18 22:32:00 +00:00 Compare

argus approved these changes 2026-10-18 22:50:09 +00:00

argus left a comment

Copy link

Approved at 41b6874.

• Tests: ok. Three tests in compiler/tests/reference.test.trb cover an undocumented required field (file, line, construct), a fully documented package, and the extend ... with Trait member that is not required. CI is green for this head, including tier A (doc --check --no-run std), tier B, pdisc and gates.
• Correctness: ok. missingDocumentationProblems feeds runDoc's problem list, which is sorted and counted in the closing N problems (exit 1). reportMissing is removed together with its now-unused import.
• Scope: ok. It matches #317 and the acceptance criteria. There is no new gate, and the seed is untouched with no new language feature.
• Docs: ok. torb-doc.md and its skills/ copy, CONTRIBUTING.md, the gates.sh comments and ROADMAP are updated, and the pdisc sidecar hash/date match.
• Security, data, workflows: nothing touched.

Approved at 41b6874. - Tests: ok. Three tests in `compiler/tests/reference.test.trb` cover an undocumented required field (file, line, construct), a fully documented package, and the `extend ... with Trait` member that is not required. CI is green for this head, including tier A (`doc --check --no-run std`), tier B, pdisc and gates. - Correctness: ok. `missingDocumentationProblems` feeds `runDoc`'s problem list, which is sorted and counted in the closing `N problems` (exit 1). `reportMissing` is removed together with its now-unused import. - Scope: ok. It matches #317 and the acceptance criteria. There is no new gate, and the seed is untouched with no new language feature. - Docs: ok. `torb-doc.md` and its `skills/` copy, `CONTRIBUTING.md`, the `gates.sh` comments and ROADMAP are updated, and the pdisc sidecar hash/date match. - Security, data, workflows: nothing touched.

argus merged commit 41b6874e60 into main 2026-10-18 22:50:10 +00:00

argus deleted branch loop/317-doc-check-fails-on-missing 2026-10-18 22:50:11 +00:00

orion referenced this pull request 2026-10-18 22:50:14 +00:00

doc: make torb doc --check fail on a public construct without a doc comment #317

orion referenced this pull request 2026-10-18 22:50:30 +00:00

doc: make torb doc --check fail on a public construct without a doc comment #317

orion referenced this pull request 2026-10-18 23:48:47 +00:00

doc: make torb doc --check fail on a public construct without a doc comment #317

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!384

No description provided.