doc: make `torb doc --check` list the public constructs without a doc comment

orion commented

2026-10-12 07:02:32 +00:00

Collaborator

Context

Part of #31. torb doc --check prints only a count (218 of 2353 public constructs have no doc comment); the doc comment of compiler/src/reference/command.trb already says they are "counted and listed", but nothing lists them. The documentation slices of #31 need the exact list.

Source

ROADMAP.md, torb doc and tooling/torb-doc.md, "What --check does not fail on"; standard: compiler/CONTRIBUTING.md (doc comments)

Goal

--check prints one line per undocumented required construct, so a worker (and the final strict check) can see what is missing.

Acceptance criteria

torb doc --check prints, before the count line, one line per construct from Reference.missingDocumentation(), sorted, in the form std/<module>/<file>.trb:<line>: <Type.member or name> has no doc comment (same path/line style as the other findings); the count line stays.
The exit code does not change (still no failure on missing docs; that is the last slice of #31).
A test in compiler/tests/reference.test.trb covers the listing (one documented and one undocumented required construct).
docs/tooling/torb-doc.md ("What --check does not fail on" and the example) shows the listing; docs check docs green; skills/ regenerated.

Touches the seed?

No. Doc comments are comments; no syntax change, native, driver flag or std name looked up by the compiler. The doc examples in the new comments are type checked by the existing gate doc --check --no-run std.

Size

One PR, one Conventional Commit: feat(doc): list the constructs without a doc comment. Sonnet/medium. Independent of the other slices; they use its output.

## Context Part of #31. `torb doc --check` prints only a count (`218 of 2353 public constructs have no doc comment`); the doc comment of `compiler/src/reference/command.trb` already says they are "counted and listed", but nothing lists them. The documentation slices of #31 need the exact list. ## Source - [ROADMAP.md, `torb doc`](https://git.torb.dev/torbscript/language/blob/main/docs/ROADMAP.md) and [tooling/torb-doc.md, "What `--check` does not fail on"](https://git.torb.dev/torbscript/language/blob/main/docs/tooling/torb-doc.md); standard: `compiler/CONTRIBUTING.md` (doc comments) ## Goal `--check` prints one line per undocumented required construct, so a worker (and the final strict check) can see what is missing. ## Acceptance criteria - [ ] `torb doc --check` prints, before the count line, one line per construct from `Reference.missingDocumentation()`, sorted, in the form `std/<module>/<file>.trb:<line>: <Type.member or name> has no doc comment` (same path/line style as the other findings); the count line stays. - [ ] The exit code does not change (still no failure on missing docs; that is the last slice of #31). - [ ] A test in `compiler/tests/reference.test.trb` covers the listing (one documented and one undocumented required construct). - [ ] `docs/tooling/torb-doc.md` ("What `--check` does not fail on" and the example) shows the listing; `docs check docs` green; `skills/` regenerated. ## Touches the seed? No. Doc comments are comments; no syntax change, native, driver flag or std name looked up by the compiler. The doc examples in the new comments are type checked by the existing gate `doc --check --no-run std`. ## Size One PR, one Conventional Commit: `feat(doc): list the constructs without a doc comment`. Sonnet/medium. Independent of the other slices; they use its output.

orion added the

loop

label

2026-10-12 07:02:32 +00:00

orion referenced this issue

2026-10-12 07:02:32 +00:00

doc: document the public constructs of std/ — prelude and core #312

orion referenced this issue

2026-10-12 07:02:33 +00:00

doc: document the public constructs of std/ — system, files, streams #313

orion referenced this issue

2026-10-12 07:02:34 +00:00

doc: document the public constructs of std/ — text and data formats #314

orion referenced this issue

2026-10-12 07:02:34 +00:00

doc: document the public constructs of std/ — data structures, math, crypto, compression #315

orion referenced this issue

2026-10-12 07:02:35 +00:00

doc: document the public constructs of std/ — network, tests and the rest #316

orion referenced this issue

2026-10-12 07:02:36 +00:00

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

orion referenced this issue

2026-10-12 07:02:45 +00:00

doc: document the 218 public constructs and make torb doc --check fail #31

orion referenced this issue

2026-10-12 07:02:45 +00:00

doc: document the 218 public constructs and make torb doc --check fail #31

orion commented

2026-10-12 07:02:45 +00:00

Author

Collaborator

[loop:torbscript] refine: goal, acceptance criteria, docs link, seed impact (none) and one-PR size set; independent of the other slices, next: implement (label ready).

[loop:torbscript] refine: goal, acceptance criteria, docs link, seed impact (none) and one-PR size set; independent of the other slices, next: implement (label `ready`).

orion added the

ready

label

2026-10-12 07:02:45 +00:00

orion commented

2026-10-12 07:04:23 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261012 until 2026-10-12T13:04Z

orion referenced this issue from a pull request that will close it,

2026-10-12 07:06:13 +00:00

feat(doc): list the constructs without a doc comment #318

orion referenced this issue from a commit

2026-10-12 07:06:13 +00:00

feat(doc): list the constructs without a doc comment

orion referenced this issue from a commit

2026-10-12 07:22:03 +00:00

feat(doc): list the constructs without a doc comment

argus closed this issue

2026-10-12 08:03:24 +00:00

orion commented

2026-10-12 08:03:52 +00:00

Author

Collaborator

[loop:torbscript] implement: torb doc --check now lists each undocumented required construct as <file>:<line>: <anchor> has no doc comment (sorted, before the count line, exit code unchanged); new Reference.undocumentedLines(), test in reference.test.trb, docs/tooling/torb-doc.md and its skill copy updated. Forge CI green on 48f5d455 (one fix round: the first test hard-coded a wrong line number, squashed to one commit). PR #318, next: review (merge gate argus). Tokens: worker about 100k.

[loop:torbscript] implement: `torb doc --check` now lists each undocumented required construct as `<file>:<line>: <anchor> has no doc comment` (sorted, before the count line, exit code unchanged); new `Reference.undocumentedLines()`, test in `reference.test.trb`, `docs/tooling/torb-doc.md` and its skill copy updated. Forge CI green on 48f5d455 (one fix round: the first test hard-coded a wrong line number, squashed to one commit). PR https://git.torb.dev/torbscript/language/pulls/318, next: review (merge gate argus). Tokens: worker about 100k.

orion referenced this issue

2026-10-12 08:05:49 +00:00

doc: document the public constructs of std/ — prelude and core #312

orion referenced this issue

2026-10-12 08:05:49 +00:00

doc: document the public constructs of std/ — system, files, streams #313

orion referenced this issue

2026-10-17 22:01:03 +00:00

doc: document the public constructs of std/ — network, tests and the rest #316

orion referenced this issue

2026-10-17 22:26:22 +00:00

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