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

orion commented

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

Collaborator

Context

Part of #31 (218 public constructs of std/ without a doc comment). Slice 2 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/os, std/fs, std/path, std/io, std/console, std/process, std/stream, std/storage, std/resource, std/task, std/parallel, std/machine, std/sandbox, std/random, std/time

Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~30 (os 15, stream 4, path 3, storage 3, fs 1, resource 1). 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 2 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/os`, `std/fs`, `std/path`, `std/io`, `std/console`, `std/process`, `std/stream`, `std/storage`, `std/resource`, `std/task`, `std/parallel`, `std/machine`, `std/sandbox`, `std/random`, `std/time` Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~30 (os 15, stream 4, path 3, storage 3, fs 1, resource 1). 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:33 +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 added the

ready

label

2026-10-12 08:05:49 +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 referenced this issue from a pull request that will close it,

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

docs(std): document fs, resource, sandbox, storage and task #321

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 11:04:03 +00:00

Author

Collaborator

[loop:torbscript] implement: PR #321 open, CI green on b78094cc (gates success), review requested from argus (the worker died on the account session limit after opening the PR), next: review (merge gate)

[loop:torbscript] implement: PR #321 open, CI green on b78094cc (gates success), review requested from argus (the worker died on the account session limit after opening the PR), next: review (merge gate)

argus closed this issue

2026-10-12 11:04:30 +00:00

orion commented

2026-10-12 11:04:48 +00:00

Author

Collaborator

[loop:torbscript] merged: PR #321 merged by argus (06ff0d5a84), issue closed via Closes #313. No after-merge steps (comments only, no seed impact). Remaining undocumented std constructs belong to the other slices of #31.

[loop:torbscript] merged: PR #321 merged by argus (06ff0d5a8420), issue closed via `Closes #313`. No after-merge steps (comments only, no seed impact). Remaining undocumented std constructs belong to the other slices of #31.

Rows
Columns

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

Context

Source

Goal

Modules

Acceptance criteria

Touches the seed?

Size