doc: make torb doc --check fail on a public construct without a doc comment #317
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Context
Last slice of #31. Once
std/has no undocumented required construct, the count intorb doc --checkbecomes a failure, and the existing tier A gatedoc --check --no-run std(tools/gates.sh) then enforces it.Source
torb docand tooling/torb-doc.md, "What--checkdoes not fail on"; standard:compiler/CONTRIBUTING.md(doc comments)Dependencies
Blocked by #311, #312, #313, #314, #315, #316 (merged;
torb doc --check --no-run stdonmainmust report 0 missing before this lands, otherwise the gate goes red).Goal
A missing doc comment on a required public construct is a problem of
--check, like a broken link.Acceptance criteria
torb doc --checkfails (exit 1, "N problems") for every required public construct without a doc comment, each finding naming file, line and construct (the listing of #311 becomes the problem list); theN of M ... have no doc commentline is dropped or kept as a summary.compiler/tests/reference.test.trb: an undocumented required construct fails, a documented one and a non-required one (e.g. a member ofextend ... with Trait) pass.doc --check --no-run stdintools/gates.shis green on the PR (it is the gate that enforces the rule; no new gate needed). Comments ingates.sh,compiler/src/reference/command.trbanddocs/tooling/torb-doc.md("What--checkdoes not fail on", the example output) updated;docs check docsgreen;skills/regenerated.torb doc --check" moves from open work to built, with the date.Touches the seed?
No (a change of the doc tool's exit rule; no syntax, native, driver flag or looked-up std name). It must be confirmed that the seed compiler can still build the tool: no new language feature is used.
Size
One PR, one Conventional Commit
feat(doc): fail the check on a missing doc comment. Sonnet/medium.torb doc --checkfail #31torb doc --checkfail #31[loop:torbscript] refine: every dependency (#311 to #316) has landed on main (#316 via
4450da99d5, whose PR reportedtorb doc --check --no-run stdat 0 missing). Goal, testable acceptance criteria and source are stated; one PR, no seed change. Labelled ready, next: implement[loop:torbscript] claim implement by session:loop-torbscript-20261019 until 2026-10-19T04:00Z
[loop:torbscript] implement:
torb doc --checknow fails on a public construct without a doc comment (one problem line per construct with file and line, counted in the closingN problems; the summary line andreportMissingare gone;Reference.undocumentedLinesbecamemissingDocumentationProblems). Tests incompiler/tests/reference.test.trbcover an undocumented construct (fails with file:line), a documented package (passes) and the member of anextend ... with Trait(not required). Docs, theskills/copy, CONTRIBUTING, thegates.shcomments and ROADMAP (strict check moved to built, 2026-10-19) updated; the CONTRIBUTING pdisc stamp refreshed. Forge CI went red twice on the runner action cache (shallow.lockin the act cache, the same flake hit a main push earlier) and once onformat --check(canon command-call style, fixed); the final run is green, includingdoc --check --no-run std. PR #384 (one commit,Closes #317), CI green on41b6874e60, next: review (waiting on merge gate argus). Claim released. Tokens: about 190k for this worker.[loop:torbscript] implement: update, PR #384 was approved and merged by argus while the worker wrote its report (landed as
41b6874e60, linear history). The PR CI was green before the merge; the push CI of main on that commit is still running. Next: close (main CI green on the landed commit, then close #317 with the commit link).[loop:torbscript] close: landed as
41b6874e60via #384; main CI on that commit is green. Issue closed, next: donetorb doc --checkfail #31