Learn Rust Coding · Lektion

Dokumentationstests

Getestete Beispiele

Dokumentationstests ist eine kostenlose Learn Rust Coding-Lektion auf CoddyKit. Dies ist Lektion 4 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des Learn Rust Coding-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der Learn Rust Coding-Kurs umfasst insgesamt 4 Lektionen.

Was sind Dokumentationstests?

Dokumentationstests sind Codebeispiele in Dokumentationskommentaren, die Cargo tatsächlich kompiliert und ausführt. Sie halten Ihre Dokumentation korrekt und sorgen dafür, dass Ihre Beispiele funktionieren.

Code in Dokumentationskommentaren

Fügen Sie Beispielcode in einem eingerahmten Codeblock (drei Backticks) innerhalb eines ///-Kommentars unter einer Überschrift # Examples ein. Die Standardsprache ist Rust.

/// Doubles a number.
///
/// # Examples
///
///     let result = my_crate::double(4);
///     assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
    n * 2
}

Dokumentationstests ausführen

Dokumentationstests werden als Teil von cargo test ausgeführt. Sie werden separat in einem Abschnitt Doc-tests aufgeführt.

cargo test

Assertions in Beispielen

Beispiele enthalten meist Assertions, damit ein fehlerhaftes Beispiel den Test fehlschlagen lässt und nicht nur kompiliert wird.

/// Returns the larger of two values.
///
/// # Examples
///
///     assert_eq!(my_crate::max(3, 7), 7);
///     assert_eq!(my_crate::max(9, 2), 9);
pub fn max(a: i32, b: i32) -> i32 {
    if a > b { a } else { b }
}

Setup-Zeilen ausblenden

Stellen Sie einer Zeile # voran, um sie auszuführen, aber in der gerenderten Dokumentation auszublenden. Nützlich für Boilerplate-Code wie Importe.

/// # Examples
///
///     # use my_crate::Counter;
///     let mut c = Counter::new();
///     c.increment();
///     assert_eq!(c.value(), 1);

Beispiele zur Verwendung des Fragezeichens

Um den Operator ? zu verwenden, schließen Sie den Body in ein verborgenes main (oder eine Hilfsfunktion) ein, das Result zurückgibt. Verborgene Zeilen beginnen mit #.

/// # Examples
///
///     # fn run() -> Result<(), std::num::ParseIntError> {
///     let n: i32 = "42".parse()?;
///     assert_eq!(n, 42);
///     # Ok(())
///     # }

no_run-Beispiele

Markieren Sie einen abgegrenzten Block mit der Annotation no_run, um ihn zu kompilieren, aber nicht auszuführen – praktisch für Beispiele, die Netzwerk- oder Dateizugriff benötigen.

/// Fetches a page (compiled but not executed).
///
/// Annotate the code fence with no_run so it is type-checked only.
pub fn fetch(url: &str) -> String {
    format!("contents of {url}")
}

ignore und should_panic

Weitere Annotationen für den Codeblock:

ignore – weder kompilieren noch ausführen
should_panic – soll einen Panic auslösen
compile_fail – soll nicht kompilieren

Warum Doc-Tests wichtig sind

Doc-Tests bieten Ihnen zwei Vorteile auf einmal:

Dokumentation, die immer korrekt ist
Kostenlose Testabdeckung für Ihre öffentlichen Beispiele

Wenn ein Beispiel nicht mehr funktioniert, schlägt die Testsuite fehl.

Crate-Name in Beispielen

Doc-Tests werden so ausgeführt, als kämen sie von außerhalb der Crate. Referenzieren Sie Elemente daher über den Crate-Namen (z. B. my_crate::func) oder über einen use-Import.

Abgegrenzte und eingerückte Blöcke

Doc-Tests akzeptieren zwei Blockstile:

Einen abgegrenzten Block mit drei Backticks, der Annotationen wie no_run ermöglicht
Einen eingerückten Block (vier Leerzeichen), wie in diesen Beispielen

Abgegrenzte Blöcke sind in echtem Code häufiger.

Schnelltest

Was bewirkt eine Zeile, die innerhalb eines Doc-Test-Codeblocks mit # beginnt?

Zusammenfassung

Sie haben Doc-Tests kennengelernt:

Code in ///-Blöcken wird von cargo test kompiliert und ausgeführt
Verwenden Sie Assertions, um das Verhalten zu überprüfen
# blendet Setup-Zeilen in der gerenderten Dokumentation aus
Annotationen: no_run, ignore, should_panic, compile_fail
Sie halten Beispiele automatisch korrekt

Häufig gestellte Fragen

Ist die Lektion „Dokumentationstests“ kostenlos?

Ja — der vollständige Text von „Dokumentationstests“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des Learn Rust Coding-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der Learn Rust Coding-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Dokumentationstests“?

Getestete Beispiele Du übst Learn Rust Coding mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um Learn Rust Coding zu starten?

Keine Vorkenntnisse erforderlich. Learn Rust Coding auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 4 von 4.

Wie lange dauert die Lektion „Dokumentationstests“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser Learn Rust Coding-Lektion Code schreiben und ausführen?

Ja. Jede Learn Rust Coding-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu Learn Rust Coding