Rustdoc: Ein Leitfaden für Anfänger zur API-Dokumentation in Rust

Dokumentation dient als Brücke zwischen Entwicklern und den Benutzern ihres Codes. Im Rust-Ökosystem wird die Dokumentation durch Rustdoc, ein ausgeklügeltes Werkzeug zur Dokumentationserstellung, das mit der Standard-Rust-Distribution ausgeliefert wird, zu einem Bürger erster Klasse erhoben. Im Gegensatz zu Dokumentationswerkzeugen in vielen anderen Sprachen generiert Rustdoc nicht nur statische Dokumentation – es erstellt interaktive, testbare und reich formatierte Dokumentationswebsites, die die Auffindbarkeit und Benutzerfreundlichkeit von Code verbessern.

Für Rust-Entwickler bietet Apidog umfassende API-Dokumentationsfunktionen für HTTP-APIs mit interaktiven Testfunktionen, visueller Antwortformatierung und kollaborativen Funktionen.

Apidog konzentriert sich auf die Dokumentation von Endpunkten, Anfrage-/Antwortformaten und HTTP-Spezifikationen, Rustdoc ist auf die Dokumentation von Code auf Sprachebene spezialisiert – die Dokumentation von Structs, Funktionen, Traits und anderen Programmierkonstrukten, aus denen ein Rust-Crate besteht. Beide Systeme haben das grundlegende Ziel, komplexe technische Systeme durch gründliche, genaue und nutzbare Dokumentation zugänglicher zu machen.

Was ist Rustdoc?

Rustdoc ist ein Befehlszeilen-Tool, das Rust-Quellcode und spezielle Dokumentationskommentare analysiert, um HTML-, CSS- und JavaScript-Dateien zu generieren, die eine durchsuchbare Dokumentationswebsite bilden. Im Kern arbeitet Rustdoc, indem es Dokumentationskommentare aus Ihrem Code extrahiert und in strukturierte Dokumentation umwandelt.

Der grundlegende Betrieb von Rustdoc umfasst:

1. Analysieren von Rust-Quelldateien, um Dokumentationskommentare zu extrahieren
2. Konvertieren dieser Kommentare von Markdown in HTML
3. Generieren einer durchsuchbaren, navigierbaren Website-Struktur
4. Extrahieren von Codebeispielen aus der Dokumentation und Vorbereiten für Tests
5. Erstellen von Querverweisen zwischen Elementen
6. Erstellen statischer Assets für die endgültige Dokumentation

Wenn die Rustdoc-Binärdatei direkt aufgerufen wird, akzeptiert sie eine Rust-Quelldatei als Eingabe:

$ rustdoc src/lib.rs --crate-name my_crate

Dieser Befehl verarbeitet die Datei lib.rs und gibt standardmäßig die Dokumentation in ein doc-Verzeichnis aus. Die Dokumentation ist hierarchisch strukturiert und spiegelt die Struktur Ihres Codes wider, mit separaten Seiten für Module, Structs, Enums, Traits und andere Rust-Konstrukte.

Im Hintergrund nutzt Rustdoc die internen APIs des Rust-Compilers, um Ihren Code zu analysieren und zu verstehen. Diese enge Integration mit dem Compiler ermöglicht es Rustdoc, genaue Querverweise zu generieren, Typsignaturen richtig zu dokumentieren und zu überprüfen, ob Codebeispiele tatsächlich kompiliert und korrekt ausgeführt werden.

Dokumentationskommentare in Rust

Die Dokumentation in Rust basiert auf einer speziellen Kommentarsyntax, die sich von regulären Codekommentaren unterscheidet. Es gibt zwei Haupttypen von Dokumentationskommentaren:

Äußere Dokumentationskommentare (///)

Äußere Dokumentationskommentare dokumentieren das Element, das ihnen folgt, und werden durch drei Schrägstriche gekennzeichnet:

/// Dies ist ein Dokumentationskommentar für die Funktion unten.
/// Er kann sich über mehrere Zeilen erstrecken und unterstützt die Markdown-Formatierung.
pub fn documented_function() -> bool {
    true
}

Diese Kommentare beschreiben Funktionen, Structs, Enums, Traits, Module und andere Elemente in Ihrer Codebasis. Sie werden als „äußere“ Dokumentation bezeichnet, da sie sich außerhalb des Elements befinden, das sie dokumentieren.

Innere Dokumentationskommentare (//!)

Innere Dokumentationskommentare dokumentieren das Element, in dem sie erscheinen, und werden durch //! gekennzeichnet:

//! Dieses Modul stellt Dienstprogramme zum Parsen von Konfigurationsdateien bereit.
//!
//! # Beispiele
//!
//! ```
//! let config = my_crate::config::parse("config.toml");
//! assert!(config.is_ok());
//! ```

pub fn parse(file_path: &str) -> Result<Config, ParseError> {
    // Implementation here
}

Innere Dokumentationskommentare werden häufig für Modul- oder Crate-Level-Dokumentation verwendet. Wenn sie am Anfang einer lib.rs-Datei platziert werden, dokumentieren sie das gesamte Crate und bilden die Titelseite Ihrer generierten Dokumentation.

Der technische Unterschied zwischen diesen Kommentarstilen ist subtil, aber wichtig: /// dokumentiert, was danach kommt, während //! dokumentiert, was es enthält.

Markdown-Unterstützung in Rustdoc

Rustdoc verwendet einen CommonMark-konformen Markdown-Parser mit mehreren Erweiterungen. Dies gibt Dokumentationsautoren Zugriff auf eine Vielzahl von Formatierungsoptionen:

Grundlegende Formatierung

/// # Überschrift Ebene 1
/// ## Überschrift Ebene 2
///
/// Absätze werden durch Leerzeilen getrennt.
///
/// *Kursiver Text* und **fetter Text** werden unterstützt.
///
/// - Ungeordnete Listen
/// - Können erstellt werden
/// - So wie diese
///
/// 1. Geordnete Listen
/// 2. Funktionieren auch
///
/// `Inline-Code` ist von Backticks umgeben.

Codeblöcke

Codeblöcke sind in Rustdoc besonders wichtig, da sie zwei Zwecken dienen: Sie zeigen Codebeispiele in der Dokumentation an und können als Tests extrahiert werden.

/// ```rust
/// // Dies ist ein Codeblock
/// let x = 5;
/// assert_eq!(x, 5);
/// ```

Wenn nach den öffnenden dreifachen Backticks keine Sprache angegeben wird, geht Rustdoc standardmäßig davon aus, dass der Codeblock Rust-Code enthält. Sie können jedoch andere Sprachen für die Syntaxhervorhebung angeben:

/// ```json
/// {
///     "name": "example",
///     "version": "1.0.0"
/// }
/// ```

Rustdoc-Erweiterungen

Rustdoc erweitert CommonMark um mehrere zusätzliche Funktionen:

Durchgestrichener Text

/// ~~Durchgestrichener Text~~ verwendet Tilden.

Fußnoten

/// Diese Aussage bedarf der Klärung[^1].
///
/// [^1]: Hier ist die Klärung.

Tabellen

/// | Header1 | Header2 |
/// |---------|---------|
/// | Zelle1   | Zelle2   |
/// | Zelle3   | Zelle4   |

Aufgabenlisten

/// - [x] Abgeschlossene Aufgabe
/// - [ ] Unvollständige Aufgabe

Intelligente Interpunktion

Rustdoc konvertiert automatisch ASCII-Interpunktionssequenzen in ihre Unicode-Äquivalente:

• -- wird zum Gedankenstrich (–)
• --- wird zum langen Gedankenstrich (—)
• ... wird zu Auslassungspunkten (…)
• Gerade Anführungszeichen werden zu geschweiften Anführungszeichen

Detaillierte Rustdoc-Befehlszeilenschnittstelle

Rustdoc bietet eine umfassende Reihe von Befehlszeilenoptionen zur Anpassung der Dokumentationsgenerierung:

$ rustdoc --help

Einige der technisch wichtigsten Optionen umfassen:

• --document-private-items: Standardmäßig dokumentiert Rustdoc nur öffentliche Elemente. Dieses Flag enthält private Elemente in der Dokumentation, was für die interne Dokumentation nützlich ist.
• --test: Führen Sie Dokumentationsbeispiele als Tests aus und überprüfen Sie, ob sie wie erwartet kompiliert und ausgeführt werden.
• --test-args: Übergeben Sie zusätzliche Argumente an den Test-Runner, z. B. --nocapture, um die Ausgabe von Tests anzuzeigen.
• --edition=EDITION: Geben Sie die Rust-Edition zum Parsen und Ausführen des Codes an (2015, 2018, 2021, 2024).
• --target=TARGET: Generieren Sie Dokumentation für die angegebene Zielplattform.
• --crate-type=TYPE: Geben Sie den Crate-Typ für Tests an (bin, lib, rlib, dylib, cdylib, staticlib, proc-macro).
• -L FLAG=PATH: Fügen Sie ein Verzeichnis zum Bibliothekssuchpfad hinzu, was für die Auflösung von Abhängigkeiten in Tests von entscheidender Bedeutung ist.
• --cfg=SPEC: Übergeben Sie ein --cfg-Flag an den Compiler, um die bedingte Kompilierung im Dokumentationscode zu aktivieren.
• --extern NAME=PATH: Geben Sie den Speicherort eines externen Crate an, damit Tests auf externe Abhängigkeiten verweisen können.

Für ein Projekt mit externen Abhängigkeiten könnte ein typischer Rustdoc-Aufruf so aussehen:

$ rustdoc src/lib.rs --crate-name example_crate \
  --edition=2021 \
  -L dependency=target/debug/deps \
  --extern serde=target/debug/deps/libserde-abcd1234.rlib \
  --extern tokio=target/debug/deps/libtokio-efgh5678.rlib

Glücklicherweise automatisiert Cargo diesen komplexen Prozess mit einem einfachen Befehl:

$ cargo doc --document-private-items

Integration mit Cargo

Cargo bietet eine optimierte Schnittstelle für die Arbeit mit Rustdoc über den Befehl cargo doc. Intern ruft Cargo Rustdoc mit den entsprechenden Parametern auf:

$ cargo doc --verbose

Wenn Sie diesen Befehl ausführen, wird der tatsächliche Rustdoc-Aufruf angezeigt, der zeigt, wie Cargo Pfade zu Abhängigkeiten und Ausgabeverzeichnissen konfiguriert.

Die Kernfunktionalität umfasst:

• cargo doc: Generieren Sie Dokumentation für das aktuelle Crate und seine Abhängigkeiten
• cargo doc --no-deps: Generieren Sie nur Dokumentation für das aktuelle Crate
• cargo doc --open: Generieren Sie Dokumentation und öffnen Sie sie in einem Webbrowser
• cargo doc --document-private-items: Fügen Sie private Elemente in die Dokumentation ein
• cargo test --doc: Führen Sie Dokumentationstests aus

Cargo ermittelt den Crate-Namen intelligent aus Ihrer Cargo.toml-Datei, richtet die richtige Ausgabeverzeichnisstruktur unter target/doc/ ein und stellt sicher, dass alle Abhängigkeiten ordnungsgemäß verknüpft sind.

Dokumentationsstruktur und -organisation

Crate-Level-Dokumentation

Die Crate-Level-Dokumentation dient als Landingpage für Ihre Bibliothek und sollte einen umfassenden Überblick bieten. Dies wird als innere Dokumentation (//!) am Anfang der Datei lib.rs geschrieben:

//! # Meine erweiterte Kryptografie-Bibliothek
//!
//! Dieses Crate bietet kryptografische Primitiven mit Fokus auf:
//!
//! - **Leistung**: Optimierte Implementierungen für moderne CPUs
//! - **Sicherheit**: Formell verifizierte Algorithmen
//! - **Benutzerfreundlichkeit**: High-Level-APIs, die schwer zu missbrauchen sind
//!
//! ## Schnellstart
//!
//! ```rust
//! use crypto_lib::{Cipher, Mode};
//!
//! let key = crypto_lib::generate_key(256);
//! let cipher = Cipher::new(&key, Mode::GCM);
//!
//! let plaintext = b"Secret message";
//! let ciphertext = cipher.encrypt(plaintext);
//! ```
//!
//! ## Funktionen
//!
//! Das Crate unterstützt die folgenden Algorithmen:
//!
//! - AES (128, 192, 256)
//! - ChaCha20
//! - Poly1305
//! - HMAC
//! - PBKDF2

Effektive Crate-Level-Dokumentation enthält oft:

1. Eine prägnante, ein Satz lange Beschreibung des Zwecks des Crate
2. Detaillierte Erläuterung der Schlüsselkonzepte und -funktionen
3. Schnellstartbeispiele, die die grundlegende Verwendung zeigen
4. Architekturübersicht für komplexere Bibliotheken
5. Funktionsflags und Konfigurationsoptionen
6. Kompatibilitätsinformationen
7. Leistungsmerkmale

Modul-Level-Dokumentation

Module fungieren als Organisationseinheiten in Rust und sollten ihre eigene Dokumentation haben, die ihren Zweck und Inhalt erklärt:

pub mod symmetric {
    //! Symmetrische Verschlüsselungsalgorithmen.
    //!
    //! Dieses Modul bietet Implementierungen von Block- und Stream-Chiffren,
    //! authentifizierten Verschlüsselungsalgorithmen und zugehörigen Dienstprogrammen.
    //!
    //! # Sicherheitsüberlegungen
    //!
    //! Alle Implementierungen wurden von [Sicherheitsfirma] geprüft
    //! und formell mit [Verifizierungstool] verifiziert.

    /// AES-Blockchiffren-Implementierung mit Unterstützung für 128-, 192- und 256-Bit-Schlüssel.
    pub struct Aes {
        // Felder hier
    }

    // Weitere Elemente...
}

Element-Level-Dokumentation

Einzelne Elemente wie Structs, Funktionen und Traits sollten eine fokussierte Dokumentation haben, die ihren Zweck, ihre Verwendung und alle besonderen Überlegungen erklärt:

/// Ein kryptografisch sicherer Zufallszahlengenerator.
///
/// Dieser CSPRNG verwendet die Entropiequelle des Systems, um
/// Zufallsbytes zu generieren, die für kryptografische Operationen geeignet sind.
///
/// # Beispiele
///
/// ```
/// use crypto_lib::CSPRNG;
///
/// let mut rng = CSPRNG::new();
/// let random_bytes = rng.generate_bytes(32);
/// ```
///
/// # Sicherheit
///
/// Unter Linux verwendet dies getrandom(2), wenn verfügbar, und greift auf /dev/urandom zurück.
/// Unter Windows verwendet es BCryptGenRandom.
/// Unter macOS verwendet es SecRandomCopyBytes.
pub struct CSPRNG {
    // Implementierungsdetails
}

impl CSPRNG {
    /// Erstellt einen neuen kryptografisch sicheren Zufallszahlengenerator.
    ///
    /// # Panics
    ///
    /// Panics, wenn die Entropiequelle des Systems nicht verfügbar ist.
    ///
    /// # Beispiele
    ///
    /// ```
    /// let rng = crypto_lib::CSPRNG::new();
    /// ```
    pub fn new() -> Self {
        // Implementierung
    }

    /// Generiert die angegebene Anzahl von Zufallsbytes.
    ///
    /// # Argumente
    ///
    /// * `len` - Die Anzahl der zu generierenden Zufallsbytes
    ///
    /// # Rückgabe
    ///
    /// Ein Vektor, der `len` kryptografisch sichere Zufallsbytes enthält.
    ///
    /// # Beispiele
    ///
    /// ```
    /// use crypto_lib::CSPRNG;
    ///
    /// let mut rng = CSPRNG::new();
    /// let key_material = rng.generate_bytes(32);
    /// assert_eq!(key_material.len(), 32);
    /// ```
    pub fn generate_bytes(&mut self, len: usize) -> Vec<u8> {
        // Implementierung
    }
}

Dokumentationstests im Detail

Eine der leistungsstärksten Funktionen von Rustdoc ist die Möglichkeit, Codebeispiele als Tests auszuführen. Dies stellt sicher, dass:

1. Beispiele in Ihrer Dokumentation tatsächlich kompiliert werden
2. Beispiele die erwarteten Ergebnisse liefern
3. Beispiele auf dem neuesten Stand bleiben, wenn sich Ihre API weiterentwickelt

Wenn Sie einen Rust-Codeblock in Ihre Dokumentation einfügen, extrahiert Rustdoc ihn und erstellt einen Testharness darum herum:

/// Addiert zwei Zahlen.
///
/// # Beispiele
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Hinter den Kulissen wandelt Rustdoc dies in eine eigenständige Testdatei um, die so aussieht:

extern crate my_crate;

fn main() {
    let result = my_crate::add(2, 3);
    assert_eq!(result, 5);
}

Diese Datei wird dann kompiliert und ausgeführt. Wenn das Programm kompiliert und ohne Panik ausgeführt wird, besteht der Test.

Testvorverarbeitung

Vor der Ausführung des Tests wendet Rustdoc mehrere Transformationen an, um einfache Beispiele ergonomischer zu gestalten:

1. Häufige Lints wie unused_variables und dead_code sind zulässig
2. Wenn das Beispiel extern crate nicht enthält und #![doc(test(no_crate_inject))] nicht angegeben wurde, wird extern crate <mycrate>; eingefügt
3. Wenn das Beispiel fn main nicht enthält, wird der Code in fn main() { ... } eingeschlossen

Mit diesen Transformationen können Sie sich auf die wichtigen Teile Ihres Beispiels konzentrieren, ohne Boilerplate.

Steuerung des Testverhaltens

Rustdoc bietet mehrere Attribute, um zu steuern, wie Tests ausgeführt werden:

• ignore: Der Code wird nicht getestet
• should_panic: Der Code sollte kompiliert werden, aber beim Ausführen panisch werden
• compile_fail: Der Code sollte nicht kompiliert werden
• no_run: Der Code wird kompiliert, aber nicht ausgeführt
• edition2015, edition2018, edition2021: Führen Sie den Code mit einer bestimmten Rust-Edition aus

Beispiele:

/// ```ignore
/// // Dieser Code wird nicht getestet
/// let x = function_that_doesnt_exist();
/// ```
///
/// ```should_panic
/// // Dieser Code sollte panisch werden
/// panic!("Dieses Beispiel demonstriert eine Panik");
/// ```
///
/// ```compile_fail
/// // Dieser Code sollte nicht kompiliert werden
/// let x: i32 = "this should not compile";
/// ```
///
/// ```no_run
/// // Dieser Code wird kompiliert, aber nicht ausgeführt
/// loop {
///     println!("Das würde für immer laufen!");
/// }
/// ```
///
/// ```edition2021
/// // Dieser Code verwendet Rust 2021-Funktionen
/// let result = try {
///     "10".parse::<i32>()?
/// };
/// ```

Verwendung von ? in Doc-Tests

Da Dokumentationsbeispiele in eine main()-Funktion eingeschlossen werden, die () zurückgibt, erfordert die Verwendung des Operators ? eine spezielle Behandlung. Es gibt zwei Ansätze:

1. Definieren Sie explizit eine main-Funktion, die ein Result zurückgibt:

/// ```
/// # fn main() -> Result<(), std::io::Error> {
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("File content: {}", content);
/// # Ok(())
/// # }
/// ```

2. Verwenden Sie eine Typannotation mit Ok(()):

/// ```
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("File content: {}", content);
/// # Ok::<(), std::io::Error>(())
/// ```

In beiden Fällen blendet das # am Anfang einiger Zeilen diese vor der gerenderten Dokumentation aus, schließt sie aber in den Test ein.

Verknüpfung zu Elementen nach Namen

Rustdoc bietet ein leistungsstarkes Querverweissystem, mit dem Dokumentationsautoren Links zu anderen Elementen in der Codebasis erstellen können. Diese Funktion verbessert die Navigierbarkeit Ihrer Dokumentation erheblich.

Intra-Doc-Links

Um einen Link zu einem anderen Element zu erstellen, verwenden Sie die Syntax [item_name]:

/// Verwendet den Typ [`HashMap`] aus der Standardbibliothek.
///
/// Es basiert auch auf der Funktion [`build_map`], die an anderer Stelle in diesem Crate definiert ist.
pub fn process_data() {
    // Implementierung
}

/// Erstellt ein neues [`HashMap`] mit vordefinierten Werten.
pub fn build_map() -> HashMap<String, i32> {
    // Implementierung
}

Wenn Rustdoc diese Links verarbeitet, löst es sie automatisch in die richtigen Elemente auf und erstellt anklickbare Hyperlinks im generierten HTML.

Pfadqualifizierung

Für präzisere Verknüpfungen, insbesondere wenn es um Elemente geht, die in verschiedenen Modulen denselben Namen haben könnten, können Sie voll qualifizierte Pfade verwenden:

/// Diese Funktion verwendet [`std::collections::HashMap`] für die Speicherung
/// und [`crate::utils::format`] zum Formatieren der Ausgabe.
pub fn complex_operation() {
    // Implementierung
}

Die Pfadauflösung folgt den Sichtbarkeitsregeln von Rust, sodass Sie nur zu Elementen verlinken können, die aus dem aktuellen Bereich sichtbar wären.

Linkziele

Sie können zu verschiedenen Arten von Elementen verlinken:

/// Verknüpfungen zu einer Struct: [`MyStruct`]
/// Verknüpfungen zu einem Enum: [`Option`]
/// Verknüpfungen zu einem Trait: [`Iterator`]
/// Verknüpfungen zu einer Funktion: [`process_data`]
/// Verknüpfungen zu einer Methode: [`MyStruct::new`]
/// Verknüpfungen zu einem Modul: [`crate::utils`]
/// Verknüpfungen zu einer Konstante: [`MAX_SIZE`]
/// Verknüpfungen zu einem Typalias: [`Result`]

Dieses umfassende Verknüpfungssystem ermöglicht es Dokumentationsautoren, ein reichhaltiges Netz miteinander verbundener Dokumentation zu erstellen, das Benutzern hilft, komplexe APIs zu navigieren.

Erweiterte Dokumentationsfunktionen

Das #[doc]-Attribut

Das #[doc]-Attribut bietet erweiterte Kontrolle über die Dokumentationsgenerierung:

// Entspricht der Verwendung von ///-Kommentaren
#[doc = "Dies ist die Dokumentation für das Element unten."]
pub struct DocumentedStruct;

// Blendet ein Element aus der Dokumentation aus
#[doc(hidden)]
pub struct InternalStruct;

// Suchaliase hinzufügen
#[doc(alias = "connection")]
#[doc(alias = "socket")]
pub struct NetworkStream;

Für bedingte Dokumentation basierend auf Funktionsflags:

/// Diese Funktion tut erstaunliche Dinge.
#[doc = "Grundlegende Fähigkeitserklärung."]
#[cfg_attr(feature = "advanced", doc = "Unterstützt auch den erweiterten Modus, wenn die Funktion 'advanced' aktiviert ist.")]
pub fn do_things() {
    // Implementierung
}

Dokumentations-Include-Muster

Für die Wiederverwendung von Inhalten in der Dokumentation:

/// # Sicherheit
///
#[doc = include_str!("../docs/common_safety_notes.md")]
pub unsafe fn perform_unsafe_operation() {
    // Implementierung
}

Auf diese Weise können Sie allgemeine Dokumentationssegmente in separaten Dateien verwalten und sie bei Bedarf einfügen, wodurch Duplizierungen reduziert und die Konsistenz sichergestellt wird.

Geschabte Beispiele

Rustdoc kann Codebeispiele automatisch aus den Test- und Beispielverzeichnissen Ihres Crate extrahieren und so zusätzlichen Kontext für die API-Nutzung bereitstellen:

$ cargo doc --document-scraped-examples

Diese Funktion funktioniert, indem sie Ihr Crate nach der Verwendung öffentlicher Elemente scannt und diese Verwendungen als Beispiele extrahiert. Es ist besonders wertvoll für komplexe APIs, bei denen Inline-Dokumentationsbeispiele möglicherweise nicht ausreichen.

Bedingte Dokumentation

Mit cfg-Attributen können Sie Dokumentation bedingt ein- oder ausschließen:

#[cfg(target_os = "windows")]
/// Windows-spezifische Implementierungsdetails.
pub fn windows_only_function() {
    // Windows-Implementierung
}

#[cfg(target_os = "linux")]
/// Linux-spezifische Implementierungsdetails.
pub fn linux_only_function() {
    // Linux-Implementierung
}

Auf diese Weise können Sie plattformspezifische oder funktionsspezifische Dokumentation erstellen, die nur angezeigt wird, wenn sie relevant ist.

Benutzerdefiniertes HTML in der Dokumentation

Für spezielle Formatierungsanforderungen ermöglicht Rustdoc das direkte Einbetten von HTML in die Dokumentation:

/// <div class="warning">
/// <strong>Warnung:</strong> Diese Funktion führt E/A aus und kann blockieren.
/// </div>
pub fn blocking_operation() {
    // Implementierung
}

In Kombination mit benutzerdefiniertem CSS ermöglicht dies eine umfassende Formatierung, die über das hinausgeht, was Markdown allein bietet.

Benutzerdefiniertes HTML und CSS

Rustdoc ermöglicht die Anpassung des Erscheinungsbilds der generierten Dokumentation durch HTML und CSS:

HTML-Vorverarbeitung

Sie können der Dokumentationsüberschrift benutzerdefiniertes HTML hinzufügen:

$ rustdoc src/lib.rs --html-in-header custom-header.html

Dies ist nützlich, um benutzerdefinierte Stylesheets, JavaScript-Bibliotheken oder Meta-Tags hinzuzufügen.

CSS-Anpassung

So wenden Sie benutzerdefiniertes CSS auf Ihre Dokumentation an:

$ rustdoc src/lib.rs --css custom-styles.css

Ihre CSS-Datei kann auf die HTML-Struktur von Rustdoc abzielen, um Farben, Schriftarten, Layouts und mehr anzupassen:

/* Ändern Sie die Haupthintergrundfarbe */
body {
    background-color: #f5f5f5;
}

/* Warnblöcke formatieren */
.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 0.5rem 1rem;
    margin: 1rem 0;
}

/* Benutzerdefinierte Formatierung für Codeblöcke */
pre {
    background-color: #282c34;
    border-radius: 6px;
    padding: 1rem;
}

Benutzerdefinierte Rendering-Themes

Rustdoc unterstützt mehrere integrierte Themes, darunter Light, Rust, Coal, Navy und Ayu. Sie können auch benutzerdefinierte Themes erstellen:

$ rustdoc src/lib.rs --theme mytheme.css

Best Practices für die Dokumentation

Technische Genauigkeit

Die Dokumentation muss technisch präzise sein. Geben Sie das genaue Verhalten, Grenzfälle und Leistungsmerkmale an:

/// Sucht mit binärer Suche nach einem Element in einem sortierten Slice.
///
/// # Komplexität
///
/// Zeitkomplexität: O(log n)
/// Raumkomplexität: O(1)
///
/// # Panics
///
/// Panics, wenn der Slice nicht in aufsteigender Reihenfolge sortiert ist.
///
/// # Beispiele
///
/// ```
/// let sorted = [1, 2, 3, 4, 5];
/// assert_eq!(my_crate::binary_search(&sorted, 3), Some(2));
/// assert_eq!(my_crate::binary_search(&sorted, 6), None);
/// ```
pub fn binary_search<T: Ord>(slice: &[T], value: T) -> Option<usize> {
    // Implementierung
}

Strukturierte Dokumentation

Befolgen Sie eine konsistente Struktur für jeden Elementtyp:

Funktionen und Methoden:

• Kurze Beschreibung
• Erklärungen der Parameter
• Beschreibung des Rückgabewerts
• Fehlerfälle
• Panics-Abschnitt (falls zutreffend)
• Beispiele
• Leistungsmerkmale
• Sicherheitsüberlegungen (für unsichere Funktionen)

Structs und Enums:

• Zweck und Beschreibung auf hoher Ebene
• Erklärungen zu Feldern/Varianten
• Konstruktionsmethoden
• Häufige Operationen
• Beispiele für die typische Verwendung

Traits:

• Vertrag und Garantien
• Erklärung der erforderlichen Methoden
• Dokumentation der bereitgestellten Methoden
• Implementierungsanleitung
• Beispiele, die Implementierung und Verwendung zeigen

Sprachpräzision

Verwenden Sie präzise Fachsprache und vermeiden Sie Mehrdeutigkeiten:

• Geben Sie anstelle von „schnell“ „O(log n) Zeitkomplexität“ an
• Geben Sie anstelle von „speichereffizient“ „verwendet konstanten Stack-Speicher“ an
• Geben Sie anstelle von „könnte fehlschlagen“ genaue Fehlerbedingungen an
• Geben Sie anstelle von „großen Eingaben“ konkrete Einschränkungen an

Versionsinformationen

Dokumentieren Sie die API-Stabilität und Versionsüberlegungen:

<