Rust
Dokumentation

Introduktion

Syntax

• /// Kommentar om yttre dokumentation (gäller för artikeln nedan)

• //! Kommentar om inre dokumentation (gäller den bifogade artikeln)

• cargo doc # Genererar dokumentation för denna bibliotekslåda.

• cargo doc --open # Genererar dokumentation för denna bibliotekslåda och öppna webbläsare.

• cargo doc -p CRATE # Genererar endast dokumentation för den angivna lådan.

• cargo doc --no-deps # Genererar dokumentation för detta bibliotek och inga beroenden.

• lasttest # Kör enhetstester och dokumentationstester.

Anmärkningar

Dokumentation Lints

För att säkerställa att alla möjliga objekt är dokumenterade kan du använda länken missing_docs att få varningar / fel från kompilatorn. För att ta emot varningar i biblioteket hela, placera detta attribut i din lib.rs fil:

#![warn(missing_docs)]

Du kan också få fel för att saknas dokumentation med detta ludd:

#![deny(missing_docs)]

Som standard är missing_docs tillåtna, men du kan uttryckligen tillåta dem med detta attribut:

#![allow(missing_docs)]

Detta kan vara användbart att placera i en modul för att tillåta saknad dokumentation för en modul, men förneka den i alla andra filer.

Dokumentation Kommentarer

Rust ger två typer av dokumentationskommentarer: inre dokumentationskommentarer och yttre dokumentationskommentarer. Exempel på var och en ges nedan.

Kommentarer om inre dokumentation

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.
    }
}

Kommentarer om yttre dokumentation

/// 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)
}

konventioner

/// 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 {
    ...
}

Dokumentationstester

Kod i dokumentationskommentarer kommer automatiskt att utföras med cargo test . Dessa är kända som "dokumentationstester" och hjälper till att se till att dina exempel fungerar och inte vilseleder användare av din låda.

Du kan importera relativt från lådroten (som om det fanns en dold extern crate mycrate; högst upp i exemplet)

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

Om din kod kanske inte körs ordentligt i ett dokumentationstest kan du använda attributet no_run , så:

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

Du kan också ange att din kod ska få panik, så här:

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