Rust
Dokumentation

Einführung

Syntax

• /// Äußerer Dokumentationskommentar (gilt für den folgenden Artikel)

• //! Innerer Dokumentationskommentar (gilt für das beiliegende Element)

• cargo doc # Erzeugt Dokumentation für diese Bibliothekskiste.

• cargo doc --open # Erzeugt Dokumentation für diese Bibliothekskiste und einen geöffneten Browser.

• cargo doc -p CRATE # Erzeugt nur Dokumentation für die angegebene Kiste.

• cargo doc --no-deps # Erzeugt Dokumentation für diese Bibliothek und keine Abhängigkeiten.

• Ladungstest # Führt Unit-Tests und Dokumentationstests durch.

Bemerkungen

Dokumentationsunterlagen

Um sicherzustellen, dass alle möglichen Elemente dokumentiert sind, können Sie den Link missing_docs , um Warnungen / Fehler vom Compiler zu erhalten. Platzieren Sie dieses Attribut in Ihrer lib.rs Datei, um Warnungen in der lib.rs Bibliothek zu erhalten:

#![warn(missing_docs)]

Sie können auch Fehler für fehlende Dokumentation mit diesem Flusen erhalten:

#![deny(missing_docs)]

Standardmäßig sind missing_docs zulässig, Sie können sie jedoch explizit mit diesem Attribut zulassen:

#![allow(missing_docs)]

Dies kann nützlich sein, wenn Sie ein Modul in einem Modul ablegen, um fehlende Dokumentation für ein Modul zuzulassen, dies aber in allen anderen Dateien ablehnen.

Kommentare zur Dokumentation

Rust bietet zwei Arten von Dokumentationskommentaren: Kommentare zur inneren Dokumentation und Kommentare zur äußeren Dokumentation. Beispiele dafür sind unten aufgeführt.

Innere Dokumentationskommentare

mod foo {
    //! Inner documentation comments go *inside* an item (e.g. a module or a 
    //! struct). They use the comment syntax //! and must go at the top of the
    //! enclosing item. 
    struct Bar {
        pub baz: i64
        //! This is invalid. Inner comments must go at the top of the struct,
        //! and must not be placed after fields.
    }
}

Äußere Dokumentationskommentare

/// Outer documentation comments go *outside* the item that they refer to.
/// They use the syntax /// to distinguish them from inner comments.
pub enum Test {
    Success,
    Fail(Error)
}

Konventionen

/// In documentation comments, you may use **Markdown**.
/// This includes `backticks` for code, *italics* and **bold**.
/// You can add headers in your documentation, like this:
/// # Notes
/// `Foo` is unsuitable for snafucating. Use `Bar` instead.
struct Foo {
    ...
}

/// It is considered good practice to have examples in your documentation
/// under an "Examples" header, like this:
/// # Examples
/// Code can be added in "fences" of 3 backticks.
///
/// ```
/// let bar = Bar::new();
/// ```
///
/// Examples also function as tests to ensure the examples actually compile.
/// The compiler will automatically generate a main() function and run the
/// example code as a test when cargo test is run.
struct Bar {
    ...
}

Dokumentationstests

Code in Dokumentationskommentaren wird automatisch durch den cargo test ausgeführt. Diese werden als "Dokumentationstests" bezeichnet und helfen sicherzustellen, dass Ihre Beispiele funktionieren und die Nutzer Ihrer Kiste nicht irregeführt werden.

Sie können relative aus der extern crate mycrate; importieren (als ob eine extern crate mycrate; oben im Beispiel).

/// ```
/// use mycrate::foo::Bar;
/// ```

Wenn Ihr Code in einem Dokumentationstest möglicherweise nicht ordnungsgemäß ausgeführt wird, können Sie das Attribut no_run wie no_run :

/// ```no_run
/// use mycrate::NetworkClient;
/// NetworkClient::login("foo", "bar");
/// ```

Sie können auch angeben, dass Ihr Code wie folgt in Panik gerät:

/// ```should_panic
/// unreachable!();
/// ```