← 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

Examples:

(DocEmit as-str 'abc) => "abc"
(DocEmit as-str 42) => "42"

(DocEmit meta-strs forms)

Take the payload of each meta form, stringified.

Parameters:

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

Returns: LIST — String list

Examples:

(DocEmit meta-strs '((note "a") (see b))) => ("a" "b")

(DocEmit param-triples ps)

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

The layouts 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

Examples:

(DocEmit param-triples '((param n INTEGER "Count"))) => (("n" "INTEGER" "Count"))
(DocEmit param-triples '((param n "Count"))) => (("n" "" ""))

(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

Examples:

(DocEmit example-pairs '((example "(+ 1 2)" "3"))) => (("(+ 1 2)" "3"))

(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

Examples:

(DocEmit returns-desc '(returns STRING "The text")) => "The text"
(DocEmit returns-desc '(returns STRING)) => ""

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 : INTEGER — Directory depth, for the relative index link
• declared? : BOOL — Whether the file declared (provide …)

Examples:

(null? (DocMd page-header "x/boot/core" "" () 2 #f)) => #t

(DocMd section title)

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

Parameters:

• title : STRING — Section title

Examples:

(DocMd section "Usage") => ## Usage

(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 “”

Examples:

(DocMd class-head "Dict" "") => ## Class `Dict`

(DocMd interface-line names)

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

Parameters:

• names : LIST — Operation name strings

Examples:

(DocMd interface-line (list "text" "note")) => **Interface:** `text` `note` 

(DocMd entry-head name)

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

Parameters:

• name : STRING — Entry name or rendered signature

Examples:

(DocMd entry-head "f") => ### `f`

(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

Examples:

(null? (DocMd alias "Str8-split")) => #t

(DocMd text s)

Emit a description paragraph.

Parameters:

• s : STRING — Paragraph text

Examples:

(DocMd text "Hello.") => Hello.

(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 “”

Examples:

(DocMd returns "STRING" "The text") => **Returns:** `STRING` — The text
(DocMd returns "LIST" "") => **Returns:** `LIST`

(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

Examples:

(DocMd see-also (list "text")) => **See also:** [`text`](#text)