Skip to the content
Diaspar

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

  1. One source. The doc string beside a definition is the documentation. The terminal's diaspar doc, (doc name) in the REPL, Markdown with an llms.txt index, the HTML site, the editor's hover and the MCP tools doc and search are all rendered from it (docs.md §0, §5).
  2. Where it is written. As today: a string after the name on def, defn, defmacro and defprotocol; doc: on types, effects, variants and fields; and now doc: on a protocol's method. A module's documentation is a string as the file's first form (docs.md §3.1).
  3. What it is. A string literal, ordinary or raw, never an expression; the tools remove the indentation, so string.dedent is not written in a doc (§3.2). The text is a Markdown subset parsed by std.doc; headings and tables only in module texts and pages.
  4. 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).
  5. Examples are tests (D016): REPL sessions run on the evaluator by diaspar test, in a fresh user session that uses the module, so they read (string.split …); in a temporary working directory; … in expected output matches anything; diaspar test --record fills in only missing output (§3.4, §9.1). REPL sessions in Markdown files a package lists are tests too (design/ai.md question 10).
  6. 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 (--private shows them). Built-in names without a definition (73 primitive functions, 37 primitive types, 29 special forms) get declaration files under std/core/, as Go's builtin package; a def naming a primitive may carry params:.
  7. Items come from the expander, with a cache per module; no program code runs to read documentation (§5).
  8. 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-editor and std.repl.show stay public and documented: macros and tools are written on them (§4.2, §4.4).
  9. What std requires: 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 in std do not cite decision numbers (§11.1).
  10. Checking: diaspar doc --check (later part of diaspar check) and a lint over std, with a per-module list of what is still owed, so the lint is on before the work is done (§9.2).
  11. File size: the limit of D032 counts documentation; std/core.dias is split into files the prelude loads in order when it passes 1,500 lines, not exempted (§11.3).
  12. 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 once std has its examples (§6, §7).
  13. The guide: std/doc/guide.md with 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).
  14. 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 in user, not the module's namespace; it gains the wildcard, the temporary directory and --record.
  • D010 §4a gains doc: on a method. D037's doc gains 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.