Commentaires de documentation : `///` pour les items, `//!` pour les modules

Les commentaires de documentation en Rust : `///` et `//!`

Au coeur du système de documentation de Rust se trouvent deux types de syntaxe de commentaires spécifiques, conçus pour être traités par l'outil `rustdoc` (accessible via `cargo doc`) afin de générer une documentation HTML. Ces commentaires utilisent le format Markdown, permettant une mise en forme riche et la possibilité d'inclure des exemples de code exécutables. Comprendre la distinction et l'usage approprié de `///` et `//!` est fondamental pour documenter efficacement un projet Rust.

Ces commentaires ne sont pas de simples notes pour le développeur lisant le code source ; ils sont la source canonique de la documentation publique de votre API. Une documentation bien rédigée utilisant ces conventions améliore considérablement la maintenabilité, la collaboration et la facilité d'utilisation de votre code par d'autres développeurs ou par vous-même à l'avenir.

L'objectif est de rendre le code auto-documenté autant que possible, en intégrant la description de son fonctionnement et de son utilisation directement à côté du code lui-même. Cela facilite la synchronisation entre le code et sa documentation.

Commentaires de documentation externe (`///`) : pour les items

Les commentaires de documentation externe, commençant par trois slashes (`///`), sont utilisés pour documenter l'item qui les suit immédiatement dans le code source. Ils sont de loin le type de commentaire de documentation le plus fréquent et s'appliquent à une vaste gamme d'éléments de code :

• Fonctions et méthodes
• Structs, enums et unions
• Champs de structs et variantes d'enums
• Traits et leurs méthodes associées
• Constantes et statiques
• Modules (lorsqu'ils sont déclarés avec `mod nom_module;` et que le commentaire est juste avant)
• Macros
• Types alias (`type NouveauNom = AncienNom;`)

Chaque ligne d'un tel commentaire doit commencer par `///`. Le contenu qui suit est interprété comme du Markdown. Il est courant de commencer par une phrase de résumé concise, suivie de paragraphes plus détaillés et de sections spécifiques comme `# Exemples`, `# Paniques`, `# Erreurs`, ou `# Sécurité`.

Voici quelques exemples d'utilisation de `///` :

/// Calcule le factoriel d'un nombre non négatif.
///
/// Retourne `n!`.
///
/// # Paniques
///
/// Panique si `n` est négatif, car le factoriel n'est pas défini pour les nombres négatifs
/// dans cette implémentation.
///
/// # Exemples
///
/// ```
/// use mon_crate::factoriel;
/// assert_eq!(factoriel(0), 1);
/// assert_eq!(factoriel(5), 120);
/// ```
pub fn factoriel(n: u64) -> u64 {
    if n == 0 {
        1
    } else {
        n * factoriel(n - 1)
    }
}

/// Représente une couleur avec des composantes Rouge, Vert, Bleu.
pub struct Couleur {
    /// La composante rouge, entre 0 et 255.
    pub rouge: u8,
    /// La composante verte, entre 0 et 255.
    pub vert: u8,
    /// La composante bleue, entre 0 et 255.
    pub bleu: u8,
}

/// Un trait pour les objets qui peuvent être dessinés.
pub trait Dessinable {
    /// Dessine l'objet sur un canevas donné.
    fn dessiner(&self, canevas: &mut String);
}

Dans ces exemples, la documentation est clairement associée à la fonction `factoriel`, au struct `Couleur` (et ses champs), et au trait `Dessinable`. Les blocs de code dans la section `# Exemples` peuvent être extraits et testés par `cargo test`, garantissant qu'ils restent corrects et à jour.

Commentaires de documentation interne (`//!`) : pour les modules et les crates

Les commentaires de documentation interne, commençant par une exclamation suivie de deux slashes (`//!`), sont utilisés pour documenter l'item qui contient le commentaire. Leur usage principal est de documenter :

• Les modules : Lorsqu'ils sont placés au tout début d'un fichier de module (par exemple, `src/mon_module.rs` ou `src/mon_module/mod.rs`), ils documentent le module `mon_module` lui-même.
• Les crates : Lorsqu'ils sont placés au tout début du fichier racine d'un crate (généralement `src/lib.rs` pour une bibliothèque ou `src/main.rs` pour un binaire), ils documentent l'ensemble du crate.

Chaque ligne de ce type de commentaire doit commencer par `//!`. Tout comme les commentaires externes, leur contenu est interprété comme du Markdown.

Exemple de `//!` pour documenter un crate (dans `src/lib.rs`) :

//! # Mon Crate Utile
//! 
//! `mon_crate_utile` est une collection de fonctions utilitaires pour
//! faciliter les tâches courantes en Rust.
//! Il fournit des outils pour la manipulation de chaînes, les opérations mathématiques,
//! et la gestion de fichiers.
//! 
//! ## Installation
//! 
//! Ajoutez la ligne suivante à votre fichier `Cargo.toml` sous `[dependencies]`:
//! 
//! ```toml
//! mon_crate_utile = "0.1.0"
//! ```
//! 
//! ## Utilisation rapide
//! 
//! Voici un exemple simple pour additionner deux nombres :
//! 
//! ```
//! use mon_crate_utile::math::additionner;
//! 
//! fn main() {
//!     assert_eq!(additionner(5, 7), 12);
//! }
//! ```

// Le reste du code du crate...
pub mod math {
    /// Additionne deux nombres `i32`.
    pub fn additionner(a: i32, b: i32) -> i32 {
        a + b
    }
}

pub mod strings {
    // ...
}

Dans cet exemple, le bloc `//!` au début de `src/lib.rs` sert de documentation principale pour le crate `mon_crate_utile`. C'est ce que les utilisateurs verront en premier lorsqu'ils consulteront la documentation du crate.

Exemple de `//!` pour documenter un module (dans `src/math.rs`, si `math` est un module déclaré dans `lib.rs` par `pub mod math;`) :

//! Ce module `math` fournit des opérations mathématiques de base.
//! 
//! Actuellement, il ne contient qu'une fonction d'addition, mais d'autres
//! opérations seront ajoutées ultérieurement.

/// Additionne deux nombres `i32`.
///
/// # Exemples
///
/// ```
/// assert_eq!(mon_crate_utile::math::additionner(10, 20), 30);
/// ```
pub fn additionner(a: i32, b: i32) -> i32 {
    a + b
}

// D'autres fonctions mathématiques pourraient suivre ici.

Ici, le commentaire `//!` documente le module `math` dans son ensemble, tandis que le commentaire `///` documente spécifiquement la fonction `additionner` à l'intérieur de ce module.

Quand utiliser `///` vs `//!` et bonnes pratiques

La règle est simple :

• Utilisez `///` (externe) pour tout ce qui est un item défini : fonction, struct, enum, trait, champ, constante, etc. Le commentaire précède l'item.
• Utilisez `//!` (interne) pour le conteneur : le module courant (au début du fichier du module) ou le crate courant (au début du fichier racine du crate).

Bonnes pratiques pour les commentaires de documentation :

• Soyez concis mais complet : La première ligne doit être un résumé. Les détails suivent.
• Utilisez Markdown efficacement : Listes, emphase, blocs de code pour les exemples, liens vers d'autres items (en utilisant `[NomDeLItem]` ou `[module::NomDeLItem]`).
• Documentez l'API publique : Tous les items `pub` devraient avoir une documentation.
• Décrivez le comportement, pas l'implémentation : Sauf si l'implémentation a des implications importantes pour l'utilisateur (par exemple, complexité algorithmique).
• Documentez les paniques, erreurs, et conditions de sécurité (`unsafe`) : Utilisez les sections `# Paniques`, `# Erreurs`, `# Sécurité` pour cela.
• Ecrivez des exemples exécutables : Les blocs de code dans les sections `# Exemples` sont testés par `cargo test`, ce qui garantit qu'ils restent à jour.

En maîtrisant l'utilisation de `///` et `//!`, vous pouvez produire une documentation claire, utile et professionnelle pour vos projets Rust, facilitant leur adoption et leur maintenance. Ces commentaires sont la fondation sur laquelle `cargo doc` construit une expérience de documentation de premier ordre.