# 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:**
```clojure
## 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:**
```rust
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).