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

orion commented

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

Collaborator

Context

Part of #31 (218 public constructs of std/ without a doc comment). Slice 1 of the documentation work; the list of what is missing comes from #311 (torb doc --check), until then from torb doc std --json (items with required and no doc).

Source

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

Goal

Every required public construct of the modules below has a doc comment that meets the standard of compiler/CONTRIBUTING.md: a first sentence that is the summary, what it does and when it fails/returns, and an # Examples block where the standard asks for one.

Modules

std/prelude, std/core

Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~55 (prelude 39, core 16). Where a module turns out to hold no required construct (e.g. plain re-exports), nothing is to be done for it.

Acceptance criteria

torb doc --check --no-run std reports zero undocumented required constructs for the modules above (their entries are gone from the list), and no new problem.
No code change besides comments; torb format --check clean on every touched file.
Examples are correct: they pass the existing gate (parse, canon, type check); where an example needs a // check or // skip first line, the reason is given.
The text is accurate to the implementation (read the code, do not guess behaviour); no private content.

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 docs(std): document <modules>. Sonnet/medium. Independent of the other documentation slices (disjoint modules).

## Context Part of #31 (218 public constructs of `std/` without a doc comment). Slice 1 of the documentation work; the list of what is missing comes from #311 (`torb doc --check`), until then from `torb doc std --json` (items with `required` and no `doc`). ## 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 Every required public construct of the modules below has a doc comment that meets the standard of `compiler/CONTRIBUTING.md`: a first sentence that is the summary, what it does and when it fails/returns, and an `# Examples` block where the standard asks for one. ## Modules `std/prelude`, `std/core` Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~55 (prelude 39, core 16). Where a module turns out to hold no required construct (e.g. plain re-exports), nothing is to be done for it. ## Acceptance criteria - [ ] `torb doc --check --no-run std` reports zero undocumented required constructs for the modules above (their entries are gone from the list), and no new problem. - [ ] No code change besides comments; `torb format --check` clean on every touched file. - [ ] Examples are correct: they pass the existing gate (parse, canon, type check); where an example needs a `// check` or `// skip` first line, the reason is given. - [ ] The text is accurate to the implementation (read the code, do not guess behaviour); no private content. ## 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 `docs(std): document <modules>`. Sonnet/medium. Independent of the other documentation slices (disjoint modules).

orion added the

loop

label

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

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 added the

ready

label

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

orion commented

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

Author

Collaborator

[loop:torbscript] refine: slice of #31 refined with the umbrella's decided-by-the-loop comment (disjoint std/ module group, doc comments only, one PR, no seed impact); #311 landed so the exact list is available via torb doc --check. ready, next: implement.
[loop:torbscript] claim implement by session:loop-torbscript-20261012 until 2026-10-12T14:05Z

[loop:torbscript] refine: slice of #31 refined with the umbrella's decided-by-the-loop comment (disjoint std/ module group, doc comments only, one PR, no seed impact); #311 landed so the exact list is available via `torb doc --check`. `ready`, next: implement. [loop:torbscript] claim implement by session:loop-torbscript-20261012 until 2026-10-12T14:05Z

orion commented

2026-10-12 08:09:08 +00:00

Author

Collaborator

[loop:torbscript] implement: no PR. The slice has nothing left to document: the "~55" estimate counted the public use re-export lines of std/prelude (39) and std/core (16), which are not constructs (a package is documented by the constructs its entry exports, each shown in the module that declares it). Measured with the 2026-10-11 nightly torb doc std --json against the bd762113 checkout (includes Buffer, Plain, the browser targets): 191 required constructs in std/core + std/prelude, 0 without a doc comment, and every file of both has a module comment. No branch pushed, no diff. Suggest closing #312 as already satisfied; #317 (flip --check) loses this slice as a dependency. Token usage: ~110k. next: waiting (nothing to implement, close or re-scope decision for the next tick)

[loop:torbscript] implement: no PR. The slice has nothing left to document: the "~55" estimate counted the `public use` re-export lines of `std/prelude` (39) and `std/core` (16), which are not constructs (a package is documented by the constructs its entry exports, each shown in the module that declares it). Measured with the 2026-10-11 nightly `torb doc std --json` against the `bd762113` checkout (includes Buffer, Plain, the browser targets): 191 required constructs in `std/core` + `std/prelude`, 0 without a doc comment, and every file of both has a module comment. No branch pushed, no diff. Suggest closing #312 as already satisfied; #317 (flip `--check`) loses this slice as a dependency. Token usage: ~110k. next: waiting (nothing to implement, close or re-scope decision for the next tick)

orion referenced this issue

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

registry: "elsewhere" owners and the signed owner file #19

orion commented

2026-10-12 08:25:56 +00:00

Author

Collaborator

[loop:torbscript] close: acceptance already satisfied (191 required constructs in std/core + std/prelude, 0 without doc comment, measured at bd762113); no PR needed. Closing as satisfied; #317 no longer waits on this slice.

[loop:torbscript] close: acceptance already satisfied (191 required constructs in std/core + std/prelude, 0 without doc comment, measured at bd762113); no PR needed. Closing as satisfied; #317 no longer waits on this slice.

orion closed this issue

2026-10-12 08:25:56 +00:00

Rows
Columns

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

Context

Source

Goal

Modules

Acceptance criteria

Touches the seed?

Size