Learn Rust Coding · Lektion

Dokumentationskommentare

///-Dokumentation

Dokumentationskommentare ist eine kostenlose Learn Rust Coding-Lektion auf CoddyKit. Dies ist Lektion 3 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.

Dokumentation in Rust

Rust bietet erstklassige, in die Sprache integrierte Dokumentation. Spezielle Kommentare werden zu HTML-Dokumentation, die von cargo doc erzeugt wird.

Äußere Dokumentationskommentare

Verwenden Sie ///, um das Element zu dokumentieren, das direkt darauf folgt — Funktionen, Structs, Enums und mehr. Der Text unterstützt Markdown.

/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Markdown-Formatierung

Dokumentationskommentare rendern Markdown: Überschriften, Listen, Fettdruck und Links funktionieren. Inline-Code wird in Backticks geschrieben, und Abschnittsüberschriften beginnen mit #.

/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
    width * height
}

Übliche Dokumentationsabschnitte

Konventionelle Überschriften erleichtern das Überfliegen der Dokumentation:

# Examples — Verwendungsbeispiele
# Panics — wann eine Panic auftritt
# Errors — welche Fehler zurückgegeben werden
# Safety — Invarianten für unsicheren Code

Innere Dokumentationskommentare

Verwenden Sie //!, um das umschließende Element zu dokumentieren, typischerweise ein Modul oder die gesamte Crate. Platzieren Sie den Kommentar am Anfang der Datei.

//! # My Math Crate
//!
//! Utilities for basic arithmetic.

pub fn double(n: i32) -> i32 {
    n * 2
}

Structs und Felder dokumentieren

Jedes öffentliche Element, einschließlich Struct-Feldern, kann einen eigenen Dokumentationskommentar haben.

/// A point in 2D space.
pub struct Point {
    /// The horizontal coordinate.
    pub x: f64,
    /// The vertical coordinate.
    pub y: f64,
}

Dokumentation erzeugen

cargo doc erstellt HTML-Dokumentation in target/doc. Fügen Sie --open hinzu, um sie im Browser anzuzeigen.

cargo doc --open

Abhängigkeiten ausschließen

Standardmäßig dokumentiert Cargo auch Ihre Abhängigkeiten. Verwenden Sie --no-deps, um nur die Dokumentation Ihrer Crate zu erstellen.

cargo doc --no-deps --open

Intra-Dokumentationslinks

Verlinken Sie andere Elemente, indem Sie ihren Pfad in eckige Klammern schreiben. Rust löst den Pfad auf und erstellt in der generierten Dokumentation einen anklickbaren Link.

/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

Warum dokumentieren?

Gute Dokumentation zahlt sich aus:

Sie wird automatisch als durchsuchbares HTML erzeugt
Beim Veröffentlichen einer Crate wird sie kostenlos auf docs.rs bereitgestellt
Beispiele in der Dokumentation werden getestet (Dokumentationstests)
Sie hilft Teammitgliedern und Ihrem zukünftigen Ich

Ein Modul dokumentieren

Kombinieren Sie innere und äußere Kommentare: Eine Moduldatei beginnt mit //!, das das Modul beschreibt, und jedes enthaltene Element verwendet ///.

//! Geometry helpers.

/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
    side * 4.0
}

Kurze Überprüfung

Welche Kommentarsyntax dokumentiert das Element, das direkt darauf folgt?

Zusammenfassung

Sie haben Dokumentationskommentare kennengelernt:

/// dokumentiert das folgende Element; //! dokumentiert das umschließende Element
Sie unterstützen Markdown und Abschnitte wie # Examples
Intra-Dokumentationslinks verbinden Elemente
cargo doc --open erzeugt und öffnet HTML-Dokumentation

Häufig gestellte Fragen

Ist die Lektion „Dokumentationskommentare“ kostenlos?

Ja — der vollständige Text von „Dokumentationskommentare“ 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 „Dokumentationskommentare“?

///-Dokumentation 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 3 von 4.

Wie lange dauert die Lektion „Dokumentationskommentare“?

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