Module docgen 

beck doc — a module’s reference documentation, derived from the module.

docs/16-packages-and-ecosystem.md §16.2 names the model: “documentation generated from types and doc-comments for every published version, automatically”. Half of that has existed since Phase 2 — crate::iface::Interface is every published name’s type, effect row and placement, and it is derived rather than declared. The other half is beck_syntax::doc.

What is generated, and what is written

Part of the page	Where it comes from
Signature — parameters, result, type arguments	Inference. Nobody writes it.
Effects — what a name performs	The inferred row (§3.2), closed at the boundary
Placement — which tier it runs on	The solver (§3.4), not an annotation
Types, fields, variants	The module’s own declarations
Prose	The ## doc comment, if there is one

Three of those five are things a language with an effect system and a placement solver knows and a hand-written reference page would get wrong within a week. That is the argument for generating this rather than writing it: a doc comment can go stale, a signature cannot.

What it deliberately does not do

• No prose is invented. A name with no doc comment is rendered with its signature and nothing else, and Docs::documented counts the difference so a coverage number is a measurement rather than an impression.
• No cross-module linking. A type from an imported module renders as its name. The Mere (§16.2) is where a link between published versions would live, and it is not built.
• Markdown in a doc comment is passed through, not parsed. The HTML renderer escapes and preserves paragraph breaks; it is not a Markdown implementation.

Structs

Docs

A module’s reference documentation.

Entry

One documented name.

Links

Where a guide’s relative links should point once it is published.

TypeEntry

One documented type, with its fields or variants.

Constants

MODULE_PAGE_HOME

Where a module page’s header link points: module pages are written into module/ beneath the site root, so the index is one level up.

REFERENCE_PAGE_HOME

Where a reference page’s header link points — they sit at the site root, beside the index.

Functions

anchor

A GitHub-flavoured heading anchor for a name.

collect_docs

Collect every doc comment in a module’s top-level items, keyed by the name it documents.

escape

Escape text for HTML. The one place &, < and > are handled, so no renderer has to remember to.

guide

A written guide as HTML: the subset of Markdown the guides in docs/ actually use.

guide_title

A guide’s own title: its first heading, without the document number docs/ files carry.

json_str

page

The site shell: one stylesheet, inline, no fonts and no scripts.

prose

A doc comment as HTML: escaped, with a blank line starting a new paragraph.