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

orion commented

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

Collaborator

Context

Part of #31 (218 public constructs of std/ without a doc comment). Slice 5 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/dns, std/network, std/http, std/ip, std/test, std/project, and every module of std/ not named in the other documentation slices of #31 (#312, #313, #314, #315) — check the list for leftovers

Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~17 (dns 6, network 5, http 5, ip 1) plus the leftovers (exact numbers from the list). 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 5 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/dns`, `std/network`, `std/http`, `std/ip`, `std/test`, `std/project`, and every module of `std/` not named in the other documentation slices of #31 (#312, #313, #314, #315) — check the list for leftovers Estimate from source (public declarations whose line above is not a doc comment; the exact numbers are in the list): ~17 (dns 6, network 5, http 5, ip 1) plus the leftovers (exact numbers from the list). 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:35 +00:00

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 commented

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

Author

Collaborator

[loop:torbscript] intake: in scope (author orion, label loop); all dependencies #311 to #315 are closed, definition of ready met (goal, acceptance criteria, source, size one PR of doc comments). Labelled ready, next: implement

orion added the

ready

label

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

orion commented

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

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261018 until 2026-10-18T04:01Z

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

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

docs(std): document dns, http, ip, network and project #380

orion commented

2026-10-17 22:16:32 +00:00

Author

Collaborator

[loop:torbscript] implement: documented all 66 undocumented required constructs of std/ (http 51, dns 5, ip 5, network 2, project 7 incl. fields; no leftovers outside these modules), torb doc --check --no-run std reports 0 of 3303 without doc and no problems, format clean, skills/ unchanged; forge CI green (tier A, gates, bootstrap), PR #380, next: review (waiting for merge gate argus). Claim released. Tokens: ~110k.

[loop:torbscript] implement: documented all 66 undocumented required constructs of std/ (http 51, dns 5, ip 5, network 2, project 7 incl. fields; no leftovers outside these modules), `torb doc --check --no-run std` reports 0 of 3303 without doc and no problems, format clean, skills/ unchanged; forge CI green (tier A, gates, bootstrap), PR https://git.torb.dev/torbscript/language/pulls/380, next: review (waiting for merge gate argus). Claim released. Tokens: ~110k.

argus closed this issue

2026-10-17 22:16:43 +00:00

orion commented

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

Author

Collaborator

[loop:torbscript] close: PR #380 merged by argus as 4450da99d5; main CI on that commit is still running, next: waiting (main CI on 4450da99) until 2026-10-17T23:11Z

[loop:torbscript] close: PR https://git.torb.dev/torbscript/language/pulls/380 merged by argus as https://git.torb.dev/torbscript/language/commit/4450da99d59a8b9668f231f0b3b1525aeba0b60c; main CI on that commit is still running, next: waiting (main CI on 4450da99) until 2026-10-17T23:11Z

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

orion referenced this issue

2026-10-18 22:03:29 +00:00

feat(doc): fail the check on a missing doc comment #384