← Index

x/doc/emit

The documentation output protocol (DocEmit) and its Markdown implementation (DocMd).

Class DocEmit

The documentation output protocol: the operations doc-gen’s walk emits through. Subclass and supply all twelve to add an output format.

Every operation is a STATIC method, so the emitter is passed as the class value itself rather than an instance.

Operations receive plain data – strings and lists of strings – never raw token forms; doc-gen owns the destructuring.

Interface: page-header section class-head interface-line entry-head alias text note params returns examples see-also

(DocEmit as-str v)

Stringify a token value the way the generator’s interpolation does.

Entry heads are sometimes symbols (a bare def) and sometimes already strings (a rendered method signature); both must render unquoted.

Parameters:

• v : ANY — Any token value

Returns: STRING — The value as display text

(DocEmit meta-strs forms)

Take the payload of each meta form, stringified.

Parameters:

• forms : LIST — (note …) or (see …) forms

Returns: LIST — String list

(DocEmit param-triples ps)

Flatten parameter forms to (name type desc) string triples, each absent field empty.

The shapes are load-bearing and predate the protocol: a THIRD element that is a string is not a type at all – it carries no type, and its description was never rendered either. Both rules are preserved rather than fixed, because the pages are a ratcheted artifact.

Parameters:

• ps : LIST — (param NAME TYPE desc) forms

Returns: LIST — List of three-element string lists

(DocEmit example-pairs exs)

Flatten example forms to (input output) string pairs.

Parameters:

• exs : LIST — (example in out) forms

Returns: LIST — List of two-element string lists

(DocEmit returns-desc ret)

A return form’s description, or empty – a non-string third element is not a description.

Parameters:

• ret : LIST — A (returns TYPE desc) form

Returns: STRING — The description text

Class DocMd

Extends DocEmit.

Markdown emitter: the reference pages under docs/ref/x, one .md per module.

Output is byte-for-byte what doc-gen emitted before the protocol existed; the sweep’s pages are unchanged.

(DocMd page-header mod desc notes depth declared?)

Emit the page header: the index back-link, the H1, the module description and its notes.

depth drives the ../ prefix on the index link; roff has no such link and ignores it.

An UNDECLARED file gets no Markdown header at all – lib/x/boot/* declares no module, and a title invented from its path would turn a page the sweep drops into one it keeps. roff is the format that structurally needs a header, so DocMan emits one either way.

Parameters:

• mod : STRING — Module name, e.g. x/type/base
• desc : STRING — Module description, or “”
• notes : LIST — Note strings
• depth : INT — Directory depth, for the relative index link
• declared? : BOOL — Whether the file declared (provide …)

(DocMd section title)

Emit a section heading – a (note “…”) form at file top level.

Parameters:

• title : STRING — Section title

(DocMd class-head cname parent)

Emit a class heading, and its parent when the class extends one.

Parameters:

• cname : STRING — Class name
• parent : STRING — Parent class name, or “”

(DocMd interface-line names)

Emit a class’s (interface …) contract – the operations a subclass must supply.

Parameters:

• names : LIST — Operation name strings

(DocMd entry-head name)

Emit the heading for one documented entry: a def, a method, or a member.

Parameters:

• name : STRING — Entry name or rendered signature

(DocMd alias name)

Record a lookup name for the next entry. Markdown has intra-page anchors already, so this is a no-op here; man output turns each one into a .so stub page.

Called with the STRUCTURED name – Class-method, not the rendered signature – because a lookup name has to be typeable.

Parameters:

• name : STRING — Lookup name for the entry that follows

(DocMd text s)

Emit a description paragraph.

Parameters:

• s : STRING — Paragraph text

(DocMd note s)

Emit one note – a caveat or contract line attached to the entry above it.

Parameters:

• s : STRING — Note text

(DocMd params ps)

Emit the parameter list. An empty type or description is omitted rather than rendered blank.

Parameters:

• ps : LIST — List of (name type desc) string triples

(DocMd returns type desc)

Emit the return type and its description.

Parameters:

• type : STRING — Return type name
• desc : STRING — Return description, or “”

(DocMd examples exs)

Emit the worked examples as an x-repl block.

The x-repl fence is what the doctest ratchet reads back; the pairs are (example INPUT OUTPUT) forms.

Parameters:

• exs : LIST — List of (input output) string pairs

(DocMd see-also names)

Emit the cross-references as intra-page anchors.

Parameters:

• names : LIST — Referenced name strings