Documentation

Rust permet d’intégrer la documentation de référence d’une bibliothèque directement dans le code. L’idée et la syntaxe ressemblent à Doxygen, mais contrairement à Doxygen le parsing du code Rust par rustdoc est impeccable. On ne se retrouve donc jamais à devoir maintenir de nombreux fragments de son code en double, une version que le générateur de documentation sait bien digérer et une version que le compilateur utilise vraiment pour générer du code… Cela tient au fait que rustdoc est développé en tandem avec le compilateur Rust, et le code pour déchiffrer le code Rust en AST est commun aux deux. Donc tout ce que rustc comprend, rustdoc le comprend aussi.

Vous avez déjà vu beaucoup d’exemples de la sortie HTML de rustdoc durant ce cours, puisque l’intégralité de la documentation de la bibliothèque standard est générée avec cet outil. J’espère donc que vous conviendrez que la présentation par défaut est aussi plus moderne, esthétique et lisible que celle de Doxygen, et que c’est globalement plus facile de naviguer dedans (davantage de liens hypertextes bien placés, barre latérale remplie plus judicieusement).

Pour tester rustdoc, il vous suffit de…

Documenter vos fonctions, types, constantes… avec des commentaires de documentation, reconnaissables à leur triple slash :

#![allow(unused)]
fn main() {
/// Calcul de la somme de x et y
fn addition(x: f32, y: f32) -> f32 {
    x + y
}
}

Documenter vos fichiers modules en les commençant par des commentaires de documentation internes, ou le troisième slash devient un point d’exclamation :

#![allow(unused)]
fn main() {
//! Gestion des entrées/sorties
}

Lancer cargo doc --open, jeter un premier coup d’oeil au résultat, et itérer longuement jusqu’à ce qu’il soit satisfaisant. Vous n’avez pas besoin de réutiliser --open pendant l’itération, ce qui ouvrirait plein d’onglets dans votre navigateur web : relancer cargo doc sans argument et rafraîchir l’onglet suffit.

Quelques conseils pour écrire des commentaires de documentation plus utiles au lecteur :

Un commentaire de documentation s’écrit comme un message de commit git : d’abord un résumé court puis deux retours à la ligne et des précisions éventuelles si besoin.

#![allow(unused)]
fn main() {
/// Représentation métaphorique du vide
///
/// Non, vraiment, ce type ne représente rien. Il ne peut être construit. Il
/// ne peut être manipulé. Il n'a vocation qu'à plonger le compilateur dans 
/// une angoisse existentielle qui le poussera à supprimer tout le code qui
/// l'utilise pour oublier la finitude de son existence.
enum Void {}
}

Ensuite, donnez si possible un exemple d’utilisation. Pour cela, vous écrivez le code Rust entre deux séries de trois backticks : ```. Ce code sera testé par cargo test, il doit donc être complet (n’oubliez pas les clauses use, si ça fait trop lourd vous pouvez les cacher ainsi que l’initialisation des variables test avec un # au début de la ligne de code).
Plus généralement, vous avez droit à une forme étendue de Markdown dans les commentaires de documentation, incluant notamment la possibilité de générer facilement des liens vers la documentation d’autres entités avec des syntaxes comme [Type], [Type::methode()]… N’hésitez pas à consulter la documentation de rustdoc pour en savoir plus.
Si votre fonction a des conditions d’erreur (retour Result<T, Erreur>, paniques, domaine de validité pour les abstractions unsafe…), documentez-les en utilisant respectivement les en-têtes conventionnels # Errors, # Panics et # Safety.

Si vous cherchez un catalogue tout fait de conventions de ce genre qui reviennent dans de nombreuses bibliothèques Rust, consultez les Rust API Guidelines et inspirez vous sans limite de la documentation de la bibliothèque standard.

Et si vous aimez bien le rendu HTML des outils de documentation du projet Rust, vous pourriez aussi vouloir explorer mdbook, l’outil utilisé pour écrire ce cours, qui est plus généralement couramment utilisé dans toutes les documentations de type manuel/tutoriel du projet Rust parce qu’il produit un rendu sympa et est très agréable à utiliser.

Rust vu du C++

Documentation