Home /Modules/manifesto/SLEELADOC.md

SLEELADOC.md

manifesto/SLEELADOC.md · 161 line(s) · markdown

SleelaDoc — the SLeeLa documentation brand

SleelaDoc is SLeeLa's in-source documentation convention: structured doc-comments that make a .sleela Wrapper™ self-describing. It is to a Sleela source file what Javadoc is to Java — but it documents intent (the Sleela mandate is "express intent, not mechanism"), not just signatures.

SleelaDoc is a comment convention, so it is fully compatible with the compiler as it exists today: every SleelaDoc block is an ordinary angle-bracket comment and is ignored by the lexer. The sleeladoc extractor (lib/sleeladoc/) parses these blocks out of any Wrapper™ without running it, and emits a Markdown or HTML API page.

Block forms (go-forward, angle-bracket style)

The go-forward house comment style is the angle-bracket form (< / <<; see comment-style.md and SLEELA.syntax §1.1). SleelaDoc is layered on top of it: a doc comment is an ordinary angle comment whose first non-whitespace token is @doc (a block) or whose line begins with < @ (a line). The @doc sentinel is what distinguishes a doc comment from an ordinary implementation note, and it is what the extractor greps for.

FormMeaning
<< @doc ... >>A SleelaDoc block — attaches to the class, struct, field, or method that immediately follows it.
< @doc ... >A SleelaDoc line — a single-line doc comment attached to the next declaration.
<< @page N: Title ... >>A page banner — marks a numbered page of a long-form document (a manifesto, spec, or essay carried in source).

Ordinary < / << (and legacy //, /* */) comments remain non-doc implementation notes — only the @doc / @page sentinel promotes a comment to SleelaDoc.

Migration note. Earlier SleelaDoc used the Java-style /** ... */, ///, and /*! page N */ forms. Those still lex as legacy comments only where the legacy /* */ and // forms are still accepted; new and edited files use the angle-bracket << @doc >> / < @doc > / << @page >> forms above, which are the go-forward house style and the forms the sleeladoc extractor recognizes. Avoid apostrophes inside an angle comment (a lexical error); phrase doc prose without contractions or possessives.

Tags

A SleelaDoc block is free prose plus optional @tags. The brand's tag set:

TagPurpose
@titleThe name of the work or unit.
@intentWhat this expresses (never how).
@paramA named parameter of a method: @param name description.
@returnsWhat a method yields.
@axiomA stated first principle taken as given.
@thesisA claim the unit argues or demonstrates.
@invariantA condition that must always hold.
@proofThe reasoning or runnable demonstration that backs a thesis.
@congruenceA structural sameness linking this unit to another (see SHEET.sheet).
@evidenceStatus of a statement: OBSERVED / DERIVED / MODELED / ASSUMED.
@toThe intended reader.
@seeA cross-reference.

Example

#sleela 2.5
material;
<< @doc
   @title    Reason
   @intent   Model the smallest unit of thought that can be checked.
   @axiom    A claim that cannot be checked is not yet knowledge.
   @thesis   Structured doubt increases the value of a belief.
   @proof    check() runs the demonstration and prints the result.
   @evidence DERIVED >>
class Reason {
  < @doc The confidence, in [0,100], after checking. >
  int confidence;

  << @doc
     @intent  Check the belief and report confidence.
     @returns the confidence in [0,100]. >>
  int check() { return confidence; }
}

The generated HTML site — /sleeladoc-api

A complete, browsable HTML documentation site for the whole standard library is generated into /sleeladoc-api by tools/generate-sleeladoc-api.py. It walks every unit under /lib, extracts the class/struct, fields, methods, and the source explanations, and emits a clean package → class → member hierarchy (blue / light blue / light grey / white, black text). Its glossary defines the reading level the prose targets — a Student 2, a capable adult learner returning to college-level study to read the books and learn what is true. Open sleeladoc-api/index.html; regenerate with:

python3 tools/generate-sleeladoc-api.py

Extracting docs — sleeladoc (the Javadoc-tool analogue)

The lib/sleeladoc/ package is the SleelaDoc extractor: the SLeeLa-side tool that reads SleelaDoc blocks out of a Wrapper™ and renders an API page, the way javadoc renders Java. It is one-class-per-file in the house style:

ClassRole
SLDocTagone parsed @tag (name + value).
SLDocCommentone SleelaDoc block: its prose plus ordered tags, and the member it attaches to.
SLDocMembera documented declaration (class / field / method) with its doc comment.
SLDocModelthe parsed model of a whole unit: its members in declaration order.
SLDocScannerthe char-cell reader that lifts @doc / @page blocks and @tags from source lines.
SLDocRendererrenders an SLDocModel as Markdown or minimal HTML.
SLSleelaDocthe façade a caller drives: scan a unit, then render.

A runnable reference lives at lib/sleeladoc/sleeladoc-demo.sleela:

# from the repository root, with the SHA-256 manifest selected
SLEELA_SHA256_MANIFEST="$(pwd)/security/sha256-manifest.json" \
  ./impl/build/sleela run lib/sleeladoc/sleeladoc-demo.sleela

Because SLeeLa's built-in String is opaque (no in-language slicing), the scanner reads an explicit char-cell String[] view of each source line — the sanctioned real char-level mechanism (see lib/text/SLString and lib/xml). The demo supplies the cells of a small documented unit and prints the rendered Markdown.

The compiler's built-in doc outputs — --wiki and the originated twin

Separate from the sleeladoc extractor, the compiler itself emits documentation for an author-marked document (the author; / authorial marker, syntax 2.4+) as a consequence of compilation — see SLEELADOC.WIKI.md for the full guide:

./impl/build/sleela compile <file.sleela> --wiki --wiki-dir=out -o out/<file>.sleela
# -> out/<file>.wiki  (MediaWiki)  and  <file>.originated.sleela  (the twin)

These are factual, structured outputs over the declared surface (classes and members), while the sleeladoc extractor renders the authored intent (the @doc prose and tags). The two are complementary: use sleeladoc for intent-level API pages, and --wiki for a branded, member-by-member catalog.

The manifesto

manifesto.sleela is the reference long-form SleelaDoc document: a runnable ~25-page "Manifesto to Thinking Kind." It predates the angle-bracket migration and is pinned at #sleela 2.1 with the legacy /** */ and /*! page N */ forms; it is the historical reference for the brand and its tag vocabulary. New SleelaDoc is authored in the angle-bracket forms above.