#314 - doc: document the public constructs of std/ — text and data formats - 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 3 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/encoding, std/binary, std/uri, std/toml, std/yaml, std/markdown, std/json, std/text, std/regex, std/expression

Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~51 (encoding 13, uri 9, toml 9, yaml 8, markdown 5, binary 5, regex 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 3 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/encoding`, `std/binary`, `std/uri`, `std/toml`, `std/yaml`, `std/markdown`, `std/json`, `std/text`, `std/regex`, `std/expression` Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~51 (encoding 13, uri 9, toml 9, yaml 8, markdown 5, binary 5, regex 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:14:56 +00:00

docs(std): document encoding, json, markdown, regex, toml, uri and yaml #351

orion commented

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

Author

Collaborator

[loop:torbscript] implement: PR #351 open, CI green on ac16119b (gates success), doc comments for 204 required constructs of std/encoding, json, markdown, regex, toml, uri and yaml (doc --check --no-run std: undocumented 297 -> 93, 0 problems; binary, text and expression have no required undocumented construct), next: review (merge gate argus). Tokens: ~450k (implement worker incl. 4 sonnet sub-workers).

[loop:torbscript] implement: PR https://git.torb.dev/torbscript/language/pulls/351 open, CI green on ac16119b (gates success), doc comments for 204 required constructs of std/encoding, json, markdown, regex, toml, uri and yaml (`doc --check --no-run std`: undocumented 297 -> 93, 0 problems; binary, text and expression have no required undocumented construct), next: review (merge gate argus). Tokens: ~450k (implement worker incl. 4 sonnet sub-workers).

argus closed this issue

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

orion commented

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

Author

Collaborator

[loop:torbscript] PR #351 merged by argus at 2026-10-12T21:58:36Z; this issue is closed. No post-merge steps (comments only, no seed impact). Remaining undocumented required constructs: 93, tracked in the other slices of #31.

Rows
Columns

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

Context

Source

Goal

Modules

Acceptance criteria

Touches the seed?

Size