Rust
Dokumentacja

Wprowadzenie

Składnia

• /// Komentarz do dokumentacji zewnętrznej (dotyczy pozycji poniżej)

• //! Komentarz do dokumentacji wewnętrznej (dotyczy załączonego elementu)

• cargo doc # Generuje dokumentację dla tej skrzynki biblioteki.

• cargo doc --open # Generuje dokumentację dla tej skrzynki biblioteki i otwartej przeglądarki.

• cargo doc -p CRATE # Generuje dokumentację tylko dla określonej skrzynki.

• cargo doc --no-deps # Generuje dokumentację dla tej biblioteki i nie ma zależności.

• test ładunku # Przeprowadza testy jednostkowe i testy dokumentacji.

Uwagi

Wskazówki dotyczące dokumentacji

Aby upewnić się, że wszystkie możliwe elementy są udokumentowane, możesz użyć łącza missing_docs aby otrzymać ostrzeżenia / błędy z kompilatora. Aby otrzymywać ostrzeżenia dla całej biblioteki, umieść ten atrybut w pliku lib.rs :

#![warn(missing_docs)]

Za pomocą tej wskazówki możesz również otrzymywać błędy dotyczące brakującej dokumentacji:

#![deny(missing_docs)]

Domyślnie missing_docs są dozwolone, ale możesz jawnie zezwolić na nie za pomocą tego atrybutu:

#![allow(missing_docs)]

Może to być przydatne, aby umieścić w jednym module, aby pozwolić na brakującą dokumentację dla jednego modułu, ale odrzuć to we wszystkich innych plikach.

Komentarze do dokumentacji

Rust udostępnia dwa typy komentarzy do dokumentacji: komentarze do dokumentacji wewnętrznej i komentarze do dokumentacji zewnętrznej. Przykłady każdego z nich podano poniżej.

Komentarze do wewnętrznej dokumentacji

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

Komentarze do dokumentacji zewnętrznej

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

Konwencje

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

Testy dokumentacji

Kod w komentarzach do dokumentacji zostanie automatycznie wykonany przez cargo test . Są to tak zwane „testy dokumentacji” i pomagają upewnić się, że twoje przykłady działają i nie wprowadzą użytkowników twojej skrzyni w błąd.

Możesz zaimportować krewnego z korzenia skrzyni (tak jakby istniała ukryta extern crate mycrate; na górze przykładu)

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

Jeśli Twój kod może nie działać poprawnie w teście dokumentacji, możesz użyć atrybutu no_run , na przykład:

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

Możesz również wskazać, że Twój kod powinien panikować, w następujący sposób:

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