Rust
Documentazione

introduzione

Sintassi

• /// Commento sulla documentazione esterna (si applica all'articolo qui sotto)

• //! Commento alla documentazione interna (si applica all'oggetto allegato)

• cargo doc # Genera documentazione per questa libreria.

• cargo doc --open # Genera documentazione per questa libreria e apre il browser.

• carico doc -p CRATE # Genera documentazione solo per la cassa specificata.

• carico doc --no-deps # Genera documentazione per questa libreria e nessuna dipendenza.

• prova di carico # Esegue test unitari e test di documentazione.

Osservazioni

Lint della documentazione

Per garantire che tutti gli elementi possibili siano documentati, è possibile utilizzare il collegamento missing_docs per ricevere avvisi / errori dal compilatore. Per ricevere avvisi in tutta la biblioteca, inserisci questo attributo nel tuo file lib.rs :

#![warn(missing_docs)]

È inoltre possibile ricevere errori per la documentazione mancante con questo filaccia:

#![deny(missing_docs)]

Per impostazione predefinita, missing_docs sono consentiti, ma puoi autorizzarli esplicitamente con questo attributo:

#![allow(missing_docs)]

Questo può essere utile da inserire in un modulo per consentire la documentazione mancante per un modulo, ma negarlo in tutti gli altri file.

Commenti sulla documentazione

Rust fornisce due tipi di commenti alla documentazione: commenti interni alla documentazione e commenti esterni alla documentazione. Esempi di ciascuno sono forniti di seguito.

Commenti della documentazione interna

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

Commenti sulla documentazione esterna

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

Convegni

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

Test di documentazione

Il codice nei commenti della documentazione verrà automaticamente eseguito dal cargo test . Questi sono noti come "test di documentazione" e aiutano a garantire che i tuoi esempi funzionino e non inducano in errore gli utenti della tua cassa.

Puoi importare i relativi dalla radice della cassa (come se ci fosse un extern crate mycrate; nascosta extern crate mycrate; in cima all'esempio)

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

Se il tuo codice non può essere eseguito correttamente in un test di documentazione, puoi utilizzare l'attributo no_run , in questo modo:

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

Puoi anche indicare che il tuo codice dovrebbe andare in panico, come questo:

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