Documenter son code efficacement (bases)

L'importance de la documentation en Rust : au-delà du code

Ecrire du code fonctionnel est une chose, mais écrire du code compréhensible et maintenable en est une autre. La documentation joue un rôle crucial pour atteindre ce second objectif. En Rust, la documentation n'est pas une réflexion après coup, mais une partie intégrante de l'écosystème, facilitée par des outils et des conventions robustes. Une bonne documentation permet aux autres développeurs (et à votre futur vous) de comprendre rapidement l'objectif, l'utilisation et le fonctionnement des différentes parties de votre code, comme les fonctions, les structs, les modules, etc.

Rust encourage la documentation directement dans le code source à l'aide de commentaires spéciaux, appelés commentaires de documentation. Ces commentaires peuvent ensuite être traités par l'outil `cargo doc` pour générer une documentation HTML de haute qualité, consultable dans un navigateur. Cette documentation peut inclure des descriptions, des exemples de code (qui peuvent même être testés !), des liens vers d'autres parties de votre API, et bien plus encore.

Investir du temps dans une documentation claire et concise améliore la collaboration, réduit la courbe d'apprentissage pour les nouveaux utilisateurs de votre bibliothèque ou application, et facilite la maintenance à long terme. Ce chapitre explore les bases pour commencer à documenter efficacement votre code Rust.

Les commentaires de documentation : `///` pour les items et `//!` pour les modules/crates

Rust distingue deux types principaux de commentaires de documentation, en fonction de ce qu'ils documentent :

• Commentaires de documentation externe (`///`) : Ces commentaires sont utilisés pour documenter l'item qui suit immédiatement le commentaire. Ils sont les plus courants et servent à documenter des fonctions, des méthodes, des structs, des enums, des traits, des modules, etc. Chaque ligne d'un commentaire de documentation externe commence par trois slashes `///`.
• Commentaires de documentation interne (`//!`) : Ces commentaires sont utilisés pour documenter l'item qui contient le commentaire. Ils sont typiquement placés au début d'un fichier de module (`mod.rs` ou `nom_du_module.rs`) pour documenter le module lui-même, ou au début du fichier racine d'un crate (`lib.rs` ou `main.rs`) pour documenter le crate dans son ensemble. Chaque ligne d'un commentaire de documentation interne commence par `//!`.

Ces commentaires supportent le format Markdown, ce qui permet d'utiliser une syntaxe simple pour structurer le texte, ajouter des listes, des blocs de code, des liens, etc.

Exemple de `///` pour documenter une fonction et un struct :

/// Calcule la somme de deux entiers `i32`.
///
/// # Exemples
///
/// ```
/// let resultat = mon_crate::additionner(2, 2);
/// assert_eq!(resultat, 4);
/// ```
pub fn additionner(a: i32, b: i32) -> i32 {
    a + b
}

/// Représente un point dans un espace 2D.
pub struct Point {
    /// La coordonnée x du point.
    pub x: f64,
    /// La coordonnée y du point.
    pub y: f64,
}

Notez l'utilisation de Markdown pour les en-têtes (`# Exemples`) et les blocs de code (```).

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

//! Ce module fournit des fonctionnalités très utiles pour manipuler des chaînes de caractères.
//! Il contient des fonctions pour inverser des chaînes, compter les mots, etc.
//! 
//! # Utilisation
//! Ajoutez `mon_super_crate` à vos dépendances dans `Cargo.toml` et utilisez les fonctions comme ceci :
//! ```
//! use mon_super_crate::mon_module;
//! // ...
//! ```

// ... contenu du module ou du crate ...

pub fn une_fonction_du_module() {
    // ...
}

La première ligne d'un commentaire de documentation est généralement un résumé concis. Les paragraphes suivants peuvent fournir plus de détails. Des sections spéciales, introduites par un en-tête Markdown (par exemple, `# Exemples`, `# Paniques`, `# Erreurs`, `# Sécurité`), sont couramment utilisées pour structurer l'information. La section `# Exemples` est particulièrement importante car `cargo test` peut exécuter ces exemples comme des tests (doctests).

Générer et consulter la documentation avec `cargo doc --open`

Une fois que vous avez ajouté des commentaires de documentation à votre code, l'outil Cargo facilite grandement la génération d'une documentation HTML professionnelle. La commande pour cela est `cargo doc`.

cargo doc

Lorsque vous exécutez cette commande à la racine de votre projet, Cargo :

1. Compile votre code (et ses dépendances, si nécessaire pour résoudre les types et les liens).
2. Extrait tous les commentaires de documentation (`///` et `//!`).
3. Utilise l'outil `rustdoc` (qui fait partie de la toolchain Rust) pour convertir ces commentaires Markdown en fichiers HTML.
4. Place la documentation générée dans le répertoire `target/doc` de votre projet.

La documentation générée inclut une page d'accueil pour votre crate, des pages pour chaque module, struct, enum, fonction, etc., avec une navigation, une fonction de recherche, et des liens entre les différents items. Elle inclut également la documentation des dépendances publiques de votre crate.

Pour générer la documentation et l'ouvrir directement dans votre navigateur web par défaut, vous pouvez utiliser l'option `--open` :

cargo doc --open

Cela vous permet de visualiser immédiatement le résultat de votre travail de documentation et de vérifier que tout s'affiche correctement.

Il est également possible de générer la documentation uniquement pour votre crate, sans celle de ses dépendances, en utilisant l'option `--no-deps` :

cargo doc --no-deps --open

Ceci peut être plus rapide si vous ne souhaitez consulter que la documentation de votre propre code.

Documenter votre code est une habitude essentielle. En utilisant les commentaires `///` et `//!` conjointement avec `cargo doc`, Rust fournit un flux de travail simple et puissant pour produire une documentation de haute qualité. Prenez le temps de documenter les interfaces publiques de vos crates et modules ; cela sera grandement apprécié par les utilisateurs de votre code et par vous-même lorsque vous y reviendrez plus tard.

Bonnes pratiques pour une documentation efficace en Rust

Ecrire une bonne documentation va au-delà de simplement ajouter des commentaires. Voici quelques bonnes pratiques à garder à l'esprit :

• Documentez tous les items publics : Toute fonction, struct, enum, trait, module ou constante qui fait partie de l'API publique de votre crate devrait être documenté. C'est ce que les utilisateurs de votre crate verront et utiliseront.
• Le résumé d'abord : La première phrase (ou le premier paragraphe court) d'un commentaire de documentation devrait être un résumé concis de ce que fait l'item. Ce résumé est souvent utilisé dans les listes d'items.
• Fournissez des exemples (`# Exemples`) : Les exemples de code sont l'un des aspects les plus utiles de la documentation. Ils montrent concrètement comment utiliser l'item. Assurez-vous que vos exemples sont compilables et corrects (`cargo test` les vérifiera s'ils sont dans des blocs de code corrects).
• Expliquez les `# Paniques` : Si une fonction peut paniquer (par exemple, en raison d'une division par zéro ou d'un index hors limites non vérifié), documentez explicitement les conditions sous lesquelles elle paniquera.
• Expliquez les `# Erreurs` : Si une fonction retourne un `Result<T, E>`, documentez les types d'erreurs (`E`) qu'elle peut retourner et dans quelles circonstances.
• Documentez les `# Sécurité` (Safety) : Si vous écrivez du code `unsafe` et que l'appelant d'une fonction `unsafe` doit respecter certains invariants pour garantir la sécurité mémoire, ces invariants doivent être clairement documentés dans une section `# Safety`.
• Utilisez Markdown judicieusement : Profitez des capacités de Markdown pour structurer votre documentation (titres, listes, emphase, liens vers d'autres items `[NomDeLItem]`), mais n'en abusez pas au point de rendre le source du commentaire difficile à lire.
• Soyez clair et précis : Evitez le jargon inutile et soyez aussi précis que possible dans vos descriptions.
• Maintenez la documentation à jour : Une documentation obsolète est pire que pas de documentation du tout. Lorsque vous modifiez le comportement d'un item, mettez à jour sa documentation en conséquence.

En suivant ces principes de base, vous pouvez créer une documentation qui améliore considérablement la qualité et la facilité d'utilisation de votre code Rust.