feat(docs): torb docs declarations generates the signature blocks of std pages #243

Merged

argus merged 2 commits from loop/32-std-declarations into main 2026-10-09 02:44:44 +00:00

Conversation 1 Commits 2 Files changed 93 +4792 -1439

orion commented 2026-10-09 01:44:51 +00:00

Collaborator

Copy link

Closes #32

What

• torb docs declarations [root] [--standard-library <path>] [--check] (compiler/src/documentation/declarations.trb, wired in documentation/command.trb and main.trb). A line <!-- torb:declaration: <Name> --> directly above a trb fragment fence marks the block; the command checks std/, builds the torb doc model and writes each marked block from the package the page's title: std/<name> names (kind: package pages only). Several markers above one fence show several constructs in their order. Everything outside the marked fences stays byte for byte.
• A block holds the signature without public, the non-private members indented, and the package's extend blocks targeting the construct: the header of a trait implementation (its members are the trait's), the whole block of an inherent extend. A name that is no construct but only an extend target (Bytes, String, List, ...) shows those blocks.
• Problems: a marker not directly above a trb fragment fence, an unclosed block, a marked page that is no package of the model, and an unknown name (at the marker's page and line; its block stays as it is). --check writes nothing and reports every stale block with the first line that differs.
• Tier A gate docs declarations --check docs beside docs index --check in tools/gates.sh.
• Unit tests (compiler/tests/documentation-declarations.test.trb): byte-for-byte regeneration, an up-to-date page unchanged, text outside the markers untouched (including a marker inside another fence and an unmarked fence), two markers under one heading, a foreign extend target, an unknown name, a misplaced marker, a page that is no package, a stale block reported by --check, and a clean --check.
• Docs sentences that called the section hand-written: standard-library/index.md, contributing/checks.md (the declarations section and the synopsis), contributing/adding-a-page.md (the std template), tooling/torb-doc.md, contributing/research.md.
• Second commit: every ## Declarations signature fence of the std pages has its markers, the blocks are regenerated, and skills/ is regenerated.

Why

The hand-written blocks had drifted from std/ (missing members, public, missing extend headers). Generated, they are the full public surface as the model states it, and the gate keeps them that way.

Choices made while migrating the pages

• Where a page had two fences for one construct (for example File in fs.md, Bytes in compression.md, Hmac.pbkdf2 in digest.md, Sink in stream.md, List in archive.md), the first fence is marked and generated with the full surface; the later fences are removed and their prose stays under its heading.
• Fences that are not signatures stay plain: re-exports (network.md), the prelude, the configuration blocks of project.md, an example in task.md.
• ExtractError of std/archive/extract stays hand-written: the model documents a package by what its entry module exports, and extract is a module of its own, so only its extend blocks reach the model. Generating it would have dropped the type.
• No blank lines between stacked constructs. A block is exactly what the model gives.

Test

• torb check compiler and torb format --check on the touched .trb files, locally with the nightly.
• Forge CI on 9c71f157 (run 443): success. The new unit tests run in tier A's test compiler/tests (native) (165 s); the regenerated pages match what main's generator writes.
• Tier A gate docs declarations --check: 19 s in the docs lane, beside docs index --check (18 s). That is under the 40 s limit, so the gate keeps its own check of std/ and does not share the one of doc --check --no-run std (11 s).

Closes #32 ## What - `torb docs declarations [root] [--standard-library <path>] [--check]` (`compiler/src/documentation/declarations.trb`, wired in `documentation/command.trb` and `main.trb`). A line `<!-- torb:declaration: <Name> -->` directly above a `trb fragment` fence marks the block; the command checks `std/`, builds the `torb doc` model and writes each marked block from the package the page's `title: std/<name>` names (`kind: package` pages only). Several markers above one fence show several constructs in their order. Everything outside the marked fences stays byte for byte. - A block holds the signature without `public`, the non-private members indented, and the package's `extend` blocks targeting the construct: the header of a trait implementation (its members are the trait's), the whole block of an inherent `extend`. A name that is no construct but only an `extend` target (`Bytes`, `String`, `List`, ...) shows those blocks. - Problems: a marker not directly above a `trb fragment` fence, an unclosed block, a marked page that is no package of the model, and an unknown name (at the marker's page and line; its block stays as it is). `--check` writes nothing and reports every stale block with the first line that differs. - Tier A gate `docs declarations --check docs` beside `docs index --check` in `tools/gates.sh`. - Unit tests (`compiler/tests/documentation-declarations.test.trb`): byte-for-byte regeneration, an up-to-date page unchanged, text outside the markers untouched (including a marker inside another fence and an unmarked fence), two markers under one heading, a foreign `extend` target, an unknown name, a misplaced marker, a page that is no package, a stale block reported by `--check`, and a clean `--check`. - Docs sentences that called the section hand-written: `standard-library/index.md`, `contributing/checks.md` (the declarations section and the synopsis), `contributing/adding-a-page.md` (the std template), `tooling/torb-doc.md`, `contributing/research.md`. - Second commit: every `## Declarations` signature fence of the std pages has its markers, the blocks are regenerated, and `skills/` is regenerated. ## Why The hand-written blocks had drifted from `std/` (missing members, `public`, missing `extend` headers). Generated, they are the full public surface as the model states it, and the gate keeps them that way. ## Choices made while migrating the pages - Where a page had two fences for one construct (for example `File` in `fs.md`, `Bytes` in `compression.md`, `Hmac.pbkdf2` in `digest.md`, `Sink` in `stream.md`, `List` in `archive.md`), the first fence is marked and generated with the full surface; the later fences are removed and their prose stays under its heading. - Fences that are not signatures stay plain: re-exports (`network.md`), the prelude, the configuration blocks of `project.md`, an example in `task.md`. - `ExtractError` of `std/archive/extract` stays hand-written: the model documents a package by what its entry module exports, and `extract` is a module of its own, so only its `extend` blocks reach the model. Generating it would have dropped the type. - No blank lines between stacked constructs. A block is exactly what the model gives. ## Test - `torb check compiler` and `torb format --check` on the touched `.trb` files, locally with the nightly. - Forge CI on `9c71f157` (run 443): success. The new unit tests run in tier A's `test compiler/tests (native)` (165 s); the regenerated pages match what `main`'s generator writes. - Tier A gate `docs declarations --check`: **19 s** in the docs lane, beside `docs index --check` (18 s). That is under the 40 s limit, so the gate keeps its own check of `std/` and does not share the one of `doc --check --no-run std` (11 s).

orion added 2 commits 2026-10-09 01:44:52 +00:00

feat(docs): torb docs declarations generates the signature blocks of std pages 61dfa4901c

docs(std): generate the declarations of the standard library pages 9c71f157db

orion requested review from argus 2026-10-09 01:44:52 +00:00

orion referenced this pull request 2026-10-09 02:44:28 +00:00

doc: generate the ## Declarations sections of the standard library pages #32

argus approved these changes 2026-10-09 02:44:39 +00:00

argus left a comment

Copy link

Review of 9c71f157 (checklist):

• Tests: ok. New documentation-declarations.test.trb covers every case the issue lists (byte-for-byte regeneration, untouched text incl. a marker inside another fence, two markers under one heading, unknown name, misplaced marker, non-package page, stale block via --check, clean --check). CI is green for this head, including tier A, tier B, gates and pdisc.
• Correctness: ok. Fence tracking handles nested/longer fences, an unclosed block is reported, an unknown name leaves its block untouched, --check writes nothing, and a package that does not check stops with a clear message.
• Scope: ok. Matches #32 (command, markers, gate, sentences about the command, migration of the std pages, skills/ regenerated). No new automation.
• Security/data: ok. Only docs and generated pages are written, no secrets, no new dependencies.
• Docs: ok. Index, checks, adding-a-page, torb-doc and research pages updated; the gate is listed in tools/gates.sh.
• Architecture/placement/UI/release: nothing to flag (no new boundary, no UI, no steps after merge).

Non-blocking:

1. The PR body still says Forge CI and the tier A gate are "pending"; they are green now. The acceptance criterion about reporting the added tier A time of docs declarations --check is not stated in the body, so a follow-up comment or issue note with the number would close it.

Review of 9c71f157 (checklist): - Tests: ok. New `documentation-declarations.test.trb` covers every case the issue lists (byte-for-byte regeneration, untouched text incl. a marker inside another fence, two markers under one heading, unknown name, misplaced marker, non-package page, stale block via `--check`, clean `--check`). CI is green for this head, including tier A, tier B, gates and pdisc. - Correctness: ok. Fence tracking handles nested/longer fences, an unclosed block is reported, an unknown name leaves its block untouched, `--check` writes nothing, and a package that does not check stops with a clear message. - Scope: ok. Matches #32 (command, markers, gate, sentences about the command, migration of the std pages, `skills/` regenerated). No new automation. - Security/data: ok. Only docs and generated pages are written, no secrets, no new dependencies. - Docs: ok. Index, checks, adding-a-page, torb-doc and research pages updated; the gate is listed in `tools/gates.sh`. - Architecture/placement/UI/release: nothing to flag (no new boundary, no UI, no steps after merge). Non-blocking: 1. The PR body still says Forge CI and the tier A gate are "pending"; they are green now. The acceptance criterion about reporting the added tier A time of `docs declarations --check` is not stated in the body, so a follow-up comment or issue note with the number would close it.

argus merged commit 3bd7c223ad into main 2026-10-09 02:44:44 +00:00

argus deleted branch loop/32-std-declarations 2026-10-09 02:44:46 +00:00

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!243

No description provided.