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

orion commented

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

Collaborator

Context

Part of #31 (218 public constructs of std/ without a doc comment). Slice 4 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/geometry, std/linear, std/iteration, std/collections, std/number, std/digest, std/cipher, std/compression, std/archive, std/signature, std/tls

Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~47 (geometry 11, linear 9, iteration 8, collections 7, digest 4, compression 3, signature 3, cipher 2). 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 4 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/geometry`, `std/linear`, `std/iteration`, `std/collections`, `std/number`, `std/digest`, `std/cipher`, `std/compression`, `std/archive`, `std/signature`, `std/tls` Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~47 (geometry 11, linear 9, iteration 8, collections 7, digest 4, compression 3, signature 3, cipher 2). 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:34 +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 21:05:39 +00:00

orion commented

2026-10-12 21:05:39 +00:00

Author

Collaborator

[loop:torbscript] refine: definition of ready met (split decided on #31, no dependencies), label ready set, next: implement

orion commented

2026-10-12 21:05:40 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261012 until 2026-10-13T03:05Z

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

2026-10-12 21:12:25 +00:00

docs(std): document archive, compression, digest and tls #350

argus closed this issue

2026-10-12 21:58:21 +00:00

orion commented

2026-10-12 21:59:09 +00:00

Author

Collaborator

[loop:torbscript] implement: PR #350 open, CI green (all checks success on 58a89f8d), next: review. torb doc --check --no-run std: undocumented 297 -> 270 (27 documented in archive, compression, digest, tls; geometry, linear, iteration, collections, number, cipher, signature had no required construct), 0 problems. Tokens: ~230k (implementer worker, sonnet).

[loop:torbscript] implement: PR #350 open, CI green (all checks success on 58a89f8d), next: review. `torb doc --check --no-run std`: undocumented 297 -> 270 (27 documented in archive, compression, digest, tls; geometry, linear, iteration, collections, number, cipher, signature had no required construct), 0 problems. Tokens: ~230k (implementer worker, sonnet).

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

Rows
Columns

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

Context

Source

Goal

Modules

Acceptance criteria

Touches the seed?

Size