Decision D041 · accepted; not implemented
Documentation is generated from doc strings and checked as code is
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-18, by the author, with every recommendation of design/docs.md section 13). Not implemented: the work plan is design/docs-plan.md. The design, its reasons, the prior art and the rejected alternatives are in docs.md; this record holds the rules.
Decision
- One source. The doc string beside a definition is the documentation. The terminal's
diaspar doc,(doc name)in the REPL, Markdown with anllms.txtindex, the HTML site, the editor's hover and the MCP toolsdocandsearchare all rendered from it (docs.md §0, §5). - Where it is written. As today: a string after the name on
def,defn,defmacroanddefprotocol;doc:on types, effects, variants and fields; and nowdoc:on a protocol's method. A module's documentation is a string as the file's first form (docs.md §3.1). - What it is. A string literal, ordinary or raw, never an expression; the tools remove the indentation, so
string.dedentis not written in a doc (§3.2). The text is a Markdown subset parsed bystd.doc; headings and tables only in module texts and pages. - Links.
[[path]]names an item and resolves as code at the item's place does; a link that names nothing is an error with candidates; a code span is never a link (§3.3). - Examples are tests (D016): REPL sessions run on the evaluator by
diaspar test, in a freshusersession that uses the module, so they read(string.split …); in a temporary working directory;…in expected output matches anything;diaspar test --recordfills in only missing output (§3.4, §9.1). REPL sessions in Markdown files a package lists are tests too (design/ai.md question 10). - What is documented (§4): modules, functions with their arities, labels and defaults, macros, values, types, fields, variants, protocols and methods, effects, items defined by macros. Private items and names beginning with
%are left out of listings and output (--privateshows them). Built-in names without a definition (73 primitive functions, 37 primitive types, 29 special forms) get declaration files understd/core/, as Go'sbuiltinpackage; adefnaming a primitive may carryparams:. - Items come from the expander, with a cache per module; no program code runs to read documentation (§5).
- Hidden modules of
std, listed in its manifest's:docs:std.rt.*,std.core.prim,std.meta.native,std.unicode.tables,std.unicode.ucd,std.test.run,std.bench.run,std.repl.std.meta,std.lang.*,std.term.raw,std.term.line-editorandstd.repl.showstay public and documented: macros and tools are written on them (§4.2, §4.4). - What
stdrequires: documentation on every public item, variant, method and field of a struct that is not opaque; a session on every public function and macro. Doc strings instddo not cite decision numbers (§11.1). - Checking:
diaspar doc --check(later part ofdiaspar check) and a lint overstd, with a per-module list of what is still owed, so the lint is on before the work is done (§9.2). - File size: the limit of D032 counts documentation;
std/core.diasis split into files the prelude loads in order when it passes 1,500 lines, not exempted (§11.3). - Outputs, in this order: the terminal, then Markdown and
llms.txt, then a static HTML site with a page per module and search on the client, built oncestdhas its examples (§6, §7). - The guide:
std/doc/guide.mdwith topics beside it, 2,000 to 3,000 tokens for the main page, embedded in the binary, tested, the differences from Clojure first;diaspar doc --guide(§8). - No stability marks (
since:,deprecated:) before the first release (§12 row 14).
What this changes
- D016 "Examples in documentation are tests": the example becomes a string after the name, without
string.dedent; it runs inuser, not the module's namespace; it gains the wildcard, the temporary directory and--record. - D010 §4a gains
doc:on a method. D037'sdocgains the flags of docs.md §6. tooling.md §3.7: HTML comes after the examples, not with the registry. - D039: ai.md question 10 is accepted.