Rust
Documentatie

Invoering

Syntaxis

• /// Opmerking buitenste documentatie (van toepassing op het onderstaande item)

• //! Opmerking binnenste documentatie (van toepassing op het bijgevoegde item)

• vrachtdocument # Genereert documentatie voor dit bibliotheekkrat.

• vrachtdocument - open # Genereert documentatie voor dit bibliotheekkrat en open browser.

• cargo doc -p CRATE # Genereert alleen documentatie voor de opgegeven krat.

• cargo doc --no-deps # Genereert documentatie voor deze bibliotheek en geen afhankelijkheden.

• ladingstest # Voert eenheids- en documentatie-tests uit.

Opmerkingen

Documentatie Linten

Om ervoor te zorgen dat alle mogelijke items worden gedocumenteerd, kunt u de link missing_docs gebruiken om waarschuwingen / fouten van de compiler te ontvangen. Om waarschuwingen voor de hele bibliotheek te ontvangen, plaatst u dit kenmerk in uw lib.rs bestand:

#![warn(missing_docs)]

U kunt ook fouten ontvangen voor ontbrekende documentatie met dit lint:

#![deny(missing_docs)]

Standaard zijn missing_docs toegestaan, maar u kunt ze expliciet toestaan met dit kenmerk:

#![allow(missing_docs)]

Dit kan handig zijn om in één module te plaatsen om ontbrekende documentatie voor één module toe te staan, maar weiger het in alle andere bestanden.

Documentatie opmerkingen

Rust biedt twee soorten documentatie-opmerkingen: opmerkingen over de interne documentatie en opmerkingen over de externe documentatie. Voorbeelden van elk worden hieronder gegeven.

Innerlijke documentatie opmerkingen

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

Opmerkingen buiten de documentatie

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

Conventies

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

Documentatietests

Code in documentatiecommentaar wordt automatisch uitgevoerd door cargo test . Deze staan bekend als "documentatietests" en helpen ervoor te zorgen dat uw voorbeelden werken en gebruikers van uw krat niet misleiden.

Je kunt relatief uit de extern crate mycrate; importeren (alsof er een verborgen extern crate mycrate; bovenaan het voorbeeld)

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

Als uw code mogelijk niet correct wordt uitgevoerd in een documentatie-test, kunt u het no_run kenmerk als volgt gebruiken:

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

Je kunt ook aangeven dat je code als volgt in paniek moet raken:

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