Rust
Documentation

Introduction

Syntaxe

• /// Commentaire sur la documentation externe (s'applique à l'article ci-dessous)

• //! Commentaire sur la documentation interne (s'applique à l'élément englobant)

• cargo doc # Génère de la documentation pour cette caisse de bibliothèque.

• cargo doc --open # Génère de la documentation pour cette bibliothèque et ce navigateur ouvert.

• cargo doc -p CRATE # Génère de la documentation pour la caisse spécifiée uniquement.

• cargo doc --no-deps # Génère de la documentation pour cette bibliothèque et aucune dépendance.

• test de la cargaison # Exécute des tests unitaires et des tests de documentation.

Remarques

Lint de documentation

Pour vous assurer que tous les éléments possibles sont documentés, vous pouvez utiliser le lien missing_docs pour recevoir des avertissements / erreurs du compilateur. Pour recevoir des avertissements à l'échelle de la bibliothèque, placez cet attribut dans votre fichier lib.rs :

#![warn(missing_docs)]

Vous pouvez également recevoir des erreurs pour la documentation manquante avec cette fibre:

#![deny(missing_docs)]

Par défaut, missing_docs est autorisé, mais vous pouvez les autoriser explicitement avec cet attribut:

#![allow(missing_docs)]

Cela peut être utile de placer dans un module pour permettre la documentation manquante pour un module, mais le refuser dans tous les autres fichiers.

Commentaires sur la documentation

Rust fournit deux types de commentaires sur la documentation: les commentaires de la documentation interne et les commentaires de la documentation externe. Des exemples de chacun sont fournis ci-dessous.

Commentaires sur la documentation interne

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

Commentaires sur la documentation externe

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

Conventions

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

Tests de documentation

Le code dans les commentaires de documentation sera automatiquement exécuté par cargo test . Celles-ci sont appelées "tests de documentation" et permettent de s'assurer que vos exemples fonctionnent et n'induisent pas les utilisateurs en erreur.

Vous pouvez importer par rapport à la racine de la caisse (comme s'il y avait une extern crate mycrate; masquée extern crate mycrate; en haut de l'exemple)

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

Si votre code risque de ne pas s'exécuter correctement dans un test de documentation, vous pouvez utiliser l'attribut no_run , comme ceci:

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

Vous pouvez également indiquer que votre code devrait paniquer, comme ceci:

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