Documentation en Rust : techniques avancées et outils

Introduction : Pourquoi la documentation en Rust est bien plus que des commentaires

L'écosystème Rust est réputé pour sa rigueur et sa fiabilité. Cependant, même le code le plus élégant est inutile sans une documentation de qualité. Au niveau débutant, il suffit d'écrire quelques lignes /// pour les fonctions publiques. Mais lorsque votre projet s'étend à plusieurs crates avec des dizaines de modules, la question des techniques avancées de documentation se pose.

Dans cet article, nous examinerons les outils et astuces qui vous aideront à créer une documentation de niveau enterprise : des tests automatiques d'exemples à la génération de livres et à l'intégration avec CI/CD.

1. Doctests : une documentation qui ne ment pas

La principale « fonctionnalité » de rustdoc est la possibilité d'intégrer des exemples de code exécutables directement dans les commentaires. Ces exemples sont automatiquement compilés et exécutés lors de l'exécution de cargo test. Cela garantit que votre documentation est toujours à jour.

Doctest de base

/// Retourne la somme de deux nombres.\n///\n/// # Exemple\n///\n/// ```\n/// let result = my_crate::add(2, 3);\n/// assert_eq!(result, 5);\n/// ```\npub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}

Astuces avancées avec doctest

Vous pouvez masquer les lignes de préparation qui ne doivent pas apparaître dans la documentation à l'aide de # :

/// # Exemple avec initialisation\n///\n/// ```\n/// # use std::collections::HashMap;\n/// let mut map = HashMap::new();\n/// map.insert("key", 42);\n/// assert_eq!(map.get("key"), Some(&42));\n/// ```

Vous pouvez également vérifier que le code ne se compile pas (par exemple, pour démontrer des erreurs de compilation) :

/// ```compile_fail\n/// let x: i32 = "chaîne"; // Erreur : incompatibilité de types\n/// ```

2. Attributs de documentation : contrôle et métadonnées

Les attributs #[doc(...)] permettent de configurer finement l'affichage de la documentation.

Masquage d'éléments

/// Fonction interne, non destinée à un usage public.\n#[doc(hidden)]\npub fn internal_helper() {}

Catégorisation et recherche

/// Groupe d'utilitaires pour le travail réseau.\n#[doc(alias = "net")]\n#[doc(alias = "socket")]\npub mod network {\n    // ...\n}

Intégration de documentation provenant d'un autre endroit

/// Voir la [documentation du module](index.html) pour des informations générales.\n#[doc(include = "docs/faq.md")]\npub fn complex_function() {}

3. Cross-references et navigation

Rustdoc prend en charge les liens vers d'autres éléments de documentation. Cela crée une structure cohérente, facile à lire.

Liens vers des fonctions et des types

/// Utilisez [`Config::new`] pour créer une instance.\n///\n/// Pour une configuration plus complexe, consultez le module [`config`].\npub struct Config { /* ... */ }

Liens vers des crates externes

/// Cette fonction utilise [serde_json] pour la sérialisation.\n///\n/// [serde_json]: https://docs.rs/serde_json\npub fn to_json() {}

4. Outils pour les grands projets : mdBook et documentation de crate

Lorsque cargo doc ne suffit plus, mdBook vient à la rescousse — un utilitaire pour créer des livres à partir de fichiers Markdown. Il est idéal pour rédiger des guides, des tutoriels et de la documentation architecturale.

Démarrage rapide avec mdBook

# Installation\ncargo install mdbook\n\n# Création d'un projet\nmdbook init my-book\ncd my-book\nmdbook serve --open

Intégration avec rustdoc

Vous pouvez intégrer la documentation de mdBook dans cargo doc à l'aide de l'attribut #[doc = include_str!()] :

/// # Architecture\n///\n/// Description détaillée de l'architecture de la bibliothèque :\n///\n#[doc = include_str!("../docs/architecture.md")]\npub mod core {\n    // ...\n}

Conclusion