SLeeLa # SLeeLa SleelaDoc — the extractor **Status: the SLeeLa-side SleelaDoc extractor — the Javadoc-tool analogue.** This directory reads **SleelaDoc** doc-comments out of a `.sleela` Wrapper™ and renders a Markdown or HTML API page, the way `javadoc` renders Java. The convention it consumes is defined in [`manifesto/SLEELADOC.md`](../../manifesto/SLEELADOC.md); this package is the tool that puts it to work. SleelaDoc documents **intent**, not just signatures (the SLeeLa mandate is "express intent, not mechanism"). A doc comment is an ordinary angle-bracket comment whose sentinel token is `@doc` (or `@page`), so it lexes as a comment today and needs no compiler change. ## The classes One SLeeLa source file per front-end object, in the house style; every class carries the Metadata Class metapattern. | File | Role | | --- | --- | | `SLDocTag.sleela` | one parsed `@tag` (name without the `@`, plus its value). | | `SLDocComment.sleela` | one SleelaDoc block: free-prose summary + ordered tags. | | `SLDocMember.sleela` | a documented declaration (class / field / method) + its doc comment and signature. | | `SLDocModel.sleela` | the parsed model of a whole unit: members in declaration order. | | `SLDocScanner.sleela` | the token-stream reader that lifts doc blocks and tags and attaches them to the following declaration. | | `SLDocRenderer.sleela` | renders an `SLDocModel` as Markdown (`toMarkdown`) or minimal HTML (`toHtml`). | | `SLSleelaDoc.sleela` | the one-object façade a caller drives (`begin` → `feed` → `toMarkdown`/`toHtml`). | | `SLPackage.sleela` | package facade. | | `sleeladoc-demo.sleela` | the runnable reference (`class SleeladocDemo` with `main`). | ## The doc-comment forms the scanner recognizes The go-forward comment style is the angle-bracket form (`<` / `<<`; see [`comment-style.md`](../../.kiro/steering/comment-style.md)). SleelaDoc layers a `@doc` / `@page` sentinel on top: | Form | Meaning | | --- | --- | | a block comment whose first content token is `@doc` | a **SleelaDoc block**, attached to the next declaration | | a line comment whose first content token is `@doc` | a **one-line SleelaDoc comment** | | a block comment whose first content token is `@page` | a **page banner** for a long-form document | Inside a block, a line whose first token is an `@tag` starts a tag (`@name` then its value); any other run is summary prose. > Because an angle comment cannot contain the angle delimiters themselves, the > literal opener/closer glyphs are described here rather than quoted: a block > opens with the two-glyph opener followed by `@doc`, runs over following lines, > and closes with the two-glyph closer. A one-line doc opens with the one-glyph > opener followed by `@doc` and closes with the one-glyph closer on the same > line. See `manifesto/SLEELADOC.md` for worked, copy-pasteable examples. ## Tags `@title`, `@intent`, `@param`, `@returns`, `@axiom`, `@thesis`, `@invariant`, `@proof`, `@congruence`, `@evidence`, `@to`, `@see`, `@page`. ## Driving it (source units currently declare syntax 2.8) The extractor's checked-in source units, `SLSleelaDoc.sleela` and `SLDocRenderer.sleela`, currently declare `#sleela 2.8`. That per-file source pragma is distinct from the compiler's maximum supported syntax edition (2.9) and from the Sleeladoc tool/package version. This README describes the extractor's token-driven API; it does not claim that its own source files have been migrated to 2.9. SLeeLa's built-in `String` is **opaque** (no in-language slicing), so — exactly as in `lib/text/SLString` and `lib/xml` — the scanner reads each source line as its **whitespace-separated tokens** (a `String[]`), which a caller produces at the char-cell boundary. A caller drives one façade object: ```java SLSleelaDoc doc = new SLSleelaDoc(); doc.begin("Reason"); // feed each tokenized source line in declaration order; // the second argument is true when the line's first token begins uppercase // (a class-type head), which the caller computes at the char-cell boundary. doc.feed(opener2("@doc"), false); // a doc block opens doc.feed(tokens("@title", "Reason"), false); doc.feed(tokens("class", "Reason", "{"), true); // ... String md = doc.toMarkdown(); // a Markdown API page String html = doc.toHtml(); // a minimal HTML fragment print(doc.documentedCount() + " / " + doc.memberCount()); ``` Run the executable reference: ```sh # 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 ``` It feeds the tokenized lines of a small documented class `Reason` (a class-level doc block, a one-line field doc, and a method doc block) and prints the rendered Markdown and HTML. ## Declaration recognition From tokens alone, the scanner records three member kinds: | First tokens | Member | | --- | --- | | `class ` | a class (kind `CLASS`) | | a type head, a name, then a `(` token | a method (kind `METHOD`) | | a type head then a name | a field (kind `FIELD`) | A *type head* is a known scalar (`void`, `int`, `long`, `boolean`, `double`, `float`, `char`, `String`, `byte`) or a token the caller flags as beginning with an uppercase letter (the SLeeLa class-name convention). A completed doc comment is held pending and attached to the next declaration recorded. ## Relationship to the compiler's built-in doc outputs The extractor renders the **authored intent** (the `@doc` prose and tags). It is complementary to the compiler's own author-marked outputs, which render the **declared surface** as a consequence of compilation: - **Wikitext emanation** — `sleela compile --wiki` → a MediaWiki page (`impl/frontend/wikigen`); see [`manifesto/SLEELADOC.WIKI.md`](../../manifesto/SLEELADOC.WIKI.md). - **Originated source twin** — `*.originated.sleela` (`impl/frontend/originate`). Use `sleeladoc` for intent-level API pages; use `--wiki` for a branded, member-by-member catalog. ## Implementation boundary The scanner classifies lines from tokens; it is a pragmatic reader for the documented surface, not a second parser (it does not type-check). Per-character HTML escaping of values is a char-cell concern handled by the `lib/xml` serializer; the identifier/short-text surface a doc page renders is passed through faithfully. These are the same honest boundaries the `lib/codecs`, `lib/compression`, and `lib/xml` families carry.