Doku-Kommentare mit `///`

Verfügbar — implementiert in Phase B.3

Wenn du jemandem (oder dir selbst in 3 Monaten) erklären willst, was deine Funktion eigentlich tut, brauchst du Doku-Kommentare. In Kiste schreibst du sie mit drei Schrägstrichen: ///.

14.1 Der Unterschied zu normalen Kommentaren

Form	Zweck	Wer sieht es?
// kommentar	Notiz für Programmierer	nur beim Lesen des Quellcodes
/* … */	Mehrere Zeilen rauskommentieren	nur beim Lesen des Quellcodes
/// doku	Offizielle Dokumentation	Programmierer + das Programm selbst (via doku())

Doku-Kommentare sind also Erklärungen mit Hand und Fuß, die zum Code dazugehören — nicht nur zum Drüber-Wegscrollen.

14.2 Eine einfache Doku schreiben

/// Berechnet die Fakultät einer Zahl.
funktion fak(n) {
    wenn n <= 1 { gib 1 }
    gib n * fak(n - 1)
}

Wichtig:

• /// muss direkt am Zeilenanfang stehen.
• Der Doku-Kommentar muss direkt vor der Deklaration stehen — keine Leerzeile dazwischen.

14.3 Mehrere Zeilen

Mehrere ///-Zeilen direkt untereinander werden automatisch zu einer Doku zusammengefasst:

/// Begrüßt eine Person.
/// Gibt einen freundlichen Text zurück.
/// Erwartet einen Namen als Text.
funktion gruss(name) {
    gib "Hallo, {name}!"
}

Die Doku ist hier:

Begrüßt eine Person.
Gibt einen freundlichen Text zurück.
Erwartet einen Namen als Text.

14.4 Doku zur Laufzeit abfragen — doku()

Hier kommt der clevere Trick: Du kannst die Doku aus deinem Programm heraus anzeigen.

/// Berechnet die Fakultät einer Zahl.
funktion fak(n) {
    wenn n <= 1 { gib 1 }
    gib n * fak(n - 1)
}

sag doku(fak)
// Ausgabe: Berechnet die Fakultät einer Zahl.

Das ist gigantisch nützlich. Du kannst dir z.B. eine Hilfe-Funktion schreiben, die zu einer Funktion ihre Doku zeigt.

14.5 Was kann eine Doku haben?

Doku-Kommentare können vor folgenden Dingen stehen:

• Funktionen — funktion …
• Klassen — klasse …
• Methoden — funktion … innerhalb einer Klasse
• Variablen — nimm … und fest …
• Module — am Anfang einer Datei (siehe 14.7)
• teile-exportierte Versionen aller obigen

/// Repräsentiert ein einfaches Tier.
klasse Tier {
    /// Erstellt ein neues Tier mit einem Namen.
    funktion neu(name) {
        dies.name = name
    }

    /// Begrüßt das Tier per Name.
    funktion gruss() {
        gib "Hallo, ich bin {dies.name}!"
    }
}

sag doku(Tier)            // Repräsentiert ein einfaches Tier.

nimm bello = neu Tier("Bello")
sag doku(bello.gruss)     // Begrüßt das Tier per Name.

14.6 Was doku() zurückgibt

Was du übergibst	Rückgabe
Eine Funktion mit ///-Doku	Der Text der Doku
Eine Methode (obj.methode) mit Doku	Der Text der Doku
Eine Klasse mit Doku	Der Text der Doku
Ein Modul mit Doku	Der Text der Doku
Etwas ohne Doku	nichts
Eine Zahl, ein Text, eine Liste, ...	nichts

14.7 Modul-Doku — die Datei selbst beschreiben

Wenn du ganz oben in einer Datei einen ///-Block hinschreibst, der NICHT direkt vor einer Deklaration steht (also durch eine Leerzeile getrennt ist), dann ist das die Doku des Moduls als Ganzes:

/// Mathe-Hilfen für tech-kiste.ch.
/// Bietet Konstanten und Funktionen rund ums Rechnen.

teile fest PI = 3.14
teile funktion quadrat(x) { gib x * x }

Wenn du dieses Modul woanders importierst, kannst du seine Doku abfragen:

nutze mathe
sag doku(mathe)
// Ausgabe:
// Mathe-Hilfen für tech-kiste.ch.
// Bietet Konstanten und Funktionen rund ums Rechnen.

14.8 Tipps für gute Dokus

Was eine gute Doku enthält:

• Was tut die Funktion — in einem Satz, ganz oben.
• Welche Argumente braucht sie? — wenn nicht offensichtlich.
• Was gibt sie zurück? — wenn nicht offensichtlich.
• Sondersituationen — was passiert bei leerer Liste, negativer Zahl, ...?

Was eine Doku nicht braucht:

• "Diese Funktion macht die Berechnung" — die heißt schon berechnung, doppelt gemoppelt.
• Selbstverständlichkeiten wie "Parameter n ist eine Zahl" — wenn das aus dem Namen klar ist.
• TODO-Notizen — die gehören in // TODO: …-Kommentare.

14.9 Häufige Fallen

Leerzeile zwischen Doku und Deklaration:

/// Das ist meine Doku

funktion f() {}    // Die Leerzeile trennt die Doku ab — kein Fehler, aber doku(f) gibt nichts zurück

So richtig:

/// Das ist meine Doku
funktion f() {}    // ok

/// mitten in einer Code-Zeile:

nimm x = 5 /// das ist KEINE Doku

Hier ist /// einfach ein normaler //-Kommentar (mit einem / als Inhalt). Doku-Kommentare wirken nur, wenn sie am Zeilenanfang stehen.

---