Dokumentation: doc-Kommentare
Lektion 4 von 7
/// für öffentliche Doku
Mit ///-Kommentaren dokumentierst du Items. cargo doc baut daraus eine
HTML-Dokumentation:
/// Addiert zwei Zahlen.
///
/// # Beispiele
///
/// ```
/// let ergebnis = addiere(2, 3);
/// assert_eq!(ergebnis, 5);
/// // → 5
/// ```
pub fn addiere(a: i32, b: i32) -> i32 {
// → 5
a + b
}
Die Code-Blöcke im ///-Kommentar werden bei cargo test als Doc-Tests
ausgeführt — Dokumentation, die sich selbst prüft.
//! dokumentiert die Crate
//!-Kommentare (am Dateianfang) dokumentieren die gesamte Crate oder das
Modul, nicht ein einzelnes Item.
Doc-Tests halten Beispiele aktuell
Code-Beispiele in ///-Kommentaren laufen bei cargo test mit. Verhält sich
dein Code anders als dokumentiert, schlägt der Doc-Test fehl. So verhindert
Rust, dass deine Doku veraltet — ein mächtiges Werkzeug.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Rufe dir die Kernpunkte in Erinnerung, bevor du die Liste aufdeckst.
⚠ Häufiger Fehler: Doc-Tests zu schreiben, die von implementierungsabhängigem Verhalten abhängen — diese Tests brechen dann bei jeder internen Änderung, obwohl die öffentliche API korrekt bleibt.
Erinnerungstraining
Tippe den fehlenden Begriff aus dem Gedächtnis ein und prüfe.