RustAst/docs/Auto_Doc_Plan.md

Automatische Dokumentationsgenerierung für Myc

Motivation

Da Myc eine proprietäre Skriptsprache ist, haben Large Language Models (LLMs) wie ChatGPT, Claude oder Gemini standardmäßig kein Wissen über ihre Syntax, Semantik oder die verfügbare Standardbibliothek (RTL). Um LLMs effektiv als Pair-Programmer für Myc-Skripte nutzen zu können, benötigen sie einen detaillierten und vor allem korrekten Kontext-Prompt.

Dieser Prompt muss die Sprachspezifikation (BNF), Konzepte (wie Series und Pipelines) und eine vollständige Referenz aller verfügbaren Funktionen und Makros enthalten. Da sich die RTL und die Sprache weiterentwickeln, ist es fehleranfällig und aufwendig, eine solche Dokumentation manuell zu pflegen.

Ziel ist es daher, die API-Dokumentation direkt aus dem Quellcode des Compilers (Rust) und den in Myc geschriebenen Standardbibliotheken (z. B. prelude.myc) zu extrahieren. Dies stellt sicher, dass die Dokumentation immer zu 100% synchron mit der Implementierung ist und korrekte Typsignaturen enthält.

Lösungsansatz: Der ## Docstring

Wir erweitern die Sprache Myc und den Compiler um einen nativen Mechanismus zur Dokumentation, der sowohl für interne Rust-Funktionen als auch für Myc-Code funktioniert.

1. Myc-Code (Der ## Kommentar)

Um in Myc geschriebene Makros und Funktionen (z. B. in prelude.myc) zu dokumentieren, führen wir einen speziellen Doc-Kommentar ein, der mit ## beginnt.

Reguläre Kommentare (mit ; oder #) werden vom Lexer weiterhin ignoriert. Wenn der Lexer jedoch auf ## stößt, extrahiert er den Text als DocComment-Token. Der Parser ordnet diesen Docstring dann der nachfolgenden Deklaration (def oder macro) als Metadatum im AST zu.

Beispiel:

## Führt den body wiederholt aus, solange cond truthy (wahr) ist.
(macro while [cond body]
  `((fn [] (if ~cond (do ~body (again))))))

2. Rust RTL (Die Laufzeitumgebung)

Für Funktionen, die in Rust implementiert sind (z. B. in math.rs), erweitern wir die Registrierungsmethoden der Environment. Jede Funktion muss bei der Registrierung zwingend einen Dokumentationsstring übergeben bekommen.

Beispiel:

register_unary("sqrt", f64::sqrt, "Calculates the square root of a float.");

Die Typinformationen (z. B. (fn [float] float)) müssen wir nicht manuell dokumentieren. Da der Compiler bereits über einen Typechecker verfügt und den StaticType jeder Funktion kennt, können wir die Signatur direkt aus dem Typ-System ableiten (z. B. über eine Display-Implementierung auf StaticType).

3. Der Generator

Wir implementieren einen neuen Befehl für das CLI-Tool: ast.exe --dump-docs.

Dieser Befehl führt folgende Schritte aus:

1. Er instanziiert die Environment und führt das normale Bootstrapping durch (Registrierung der Rust-Funktionen und Auswertung von prelude.myc).
2. Dabei sammelt die Environment alle Docstrings und Typ-Signaturen zentral in einer Registry.
3. Der Generator lädt die statischen Basis-Informationen (Syntax & Semantik) aus docs/BNF.md.
4. Anschließend formatiert er alle registrierten Funktionen und Makros als saubere Markdown-Blöcke.
5. Beide Teile (BNF + API-Referenz) werden zusammengefügt und als vollständiger LLM-Prompt (z. B. docs/Myc_LLM_Prompt.md) ausgegeben.

Roadmap

1. Lexer/Parser: Unterstützung für ## DocComments in lexer.rs und parser.rs implementieren.
2. AST: Das Feld doc: Option<String> zu den Def- und MacroDecl-Knoten hinzufügen.
3. Environment: Eine Registry für Dokumentation (HashMap<Symbol, String>) in der Environment anlegen.
4. RTL: Alle Rust-Funktionen (z. B. in math.rs, core.rs) mit Docstrings ausstatten und die Signaturen zur Laufzeit generieren.
5. Generator: Den Befehl --dump-docs im CLI implementieren und die Generierung des finalen Markdown-Dokuments aufsetzen.
6. Testsuite: Einen Integrationstest hinzufügen, der prüft, ob die generierte Doku im Repository aktuell ist (Schutz vor Drift).