Documentation en Rust : comment écrire du code qui parle de lui-même

Pourquoi la documentation en Rust n'est pas une corvée ennuyeuse, mais un super-pouvoir

Imaginez que vous ouvrez un crate inconnu en Rust, et qu'il n'y a rien. Aucun commentaire, aucune ligne de documentation. Seulement du code brut avec des génériques, des traits et des durées de vie. Ça vous dit quelque chose ? C'est douloureux, non ? C'est pourquoi le sujet de la documentation dans les projets Rust est plus pertinent que jamais.

Rust est réputé pour sa sécurité et ses performances, mais son système de types peut être complexe pour les débutants. Une bonne documentation transforme votre code d'un "charabia incompréhensible" en un guide clair. De plus, en Rust, la documentation n'est pas seulement du texte. Ce sont des exemples exécutables qui garantissent que votre code fonctionne comme promis.

Dans cet article, nous allons explorer les bonnes pratiques de documentation de code en Rust qui vous aideront à écrire des projets clairs, maintenables et professionnels. Vous apprendrez à utiliser rustdoc, à formater correctement les commentaires doc et à créer une documentation dont les utilisateurs de votre code vous seront reconnaissants.

Les bases : qu'est-ce que la documentation en Rust et pourquoi en a-t-on besoin

En Rust, il existe deux types de commentaires : les commentaires normaux (// et /* */) et les commentaires doc (/// et //!). Les commentaires doc sont automatiquement collectés par l'outil rustdoc et transformés en documentation HTML. C'est un outil intégré qui accompagne le compilateur — vous n'avez rien à installer en plus.

Pourquoi perdre du temps sur la documentation ? Voici trois raisons en béton :

• Vitesse de développement : vous oublierez votre code dans un mois. La documentation est un pense-bête pour votre futur vous.
• Intégration des nouveaux développeurs : une bonne documentation réduit le temps d'adaptation à un projet de semaines à heures.
• Des tests en bonus : les exemples dans les commentaires doc peuvent être exécutés comme des tests. On appelle cela des doctests.

Regardons un exemple simple. Voici à quoi ressemble une documentation de base pour une fonction :

/// Calcule la factorielle d'un nombre n////// # Arguments////// * `n` - Un entier non négatif////// # Returns////// Retourne un `u64` - la factorielle du nombre n////// # Examples////// ```/// use my_crate::math::factorial;////// assert_eq!(factorial(5), 120);/// ```pub fn factorial(n: u64) -> u64 {    (1..=n).product()}

Exécutez cargo doc --open, et vous verrez une belle page HTML formatée avec cette description. Et si vous lancez cargo test, l'exemple dans la documentation sera également exécuté comme un test. Pratique, non ?

Structure d'un bon commentaire doc : les secrets des professionnels

Écrire de la documentation est un art. Dans la communauté Rust, certaines normes se sont établies pour rendre la documentation utile et uniforme. Décortiquons-les.

Le premier paragraphe est un titre

La première ligne d'un commentaire doc doit être une brève description de ce que fait la fonction, la structure ou le module. rustdoc l'utilise pour créer une liste succincte de tous les éléments. Imaginez que c'est le titre d'un article d'actualité — il doit immédiatement indiquer de quoi il s'agit.

/// Trie un tableau avec la méthode à bulles (Bubble Sort).////// Une description détaillée peut être ajoutée ici...pub fn bubble_sort(arr: &mut [i32]) { ... }

Sections : utilisez les titres Markdown

Rust prend en charge Markdown dans les commentaires doc. Utilisez des sections standard pour structurer l'information :

• # Examples — exemples d'utilisation
• # Panics — quand la fonction peut provoquer une panique
• # Errors — quelles erreurs sont retournées (si elle retourne un Result)
• # Safety — si la fonction est unsafe, expliquez pourquoi
• # Arguments — description des paramètres