
III. Aller plus loin
2. Documentation et rustdoc
En plus du compilateur, Rust possède un générateur de documentation. Toute la documentation en ligne de l'API (disponible ici) a été générée avec cet outil. Vous allez voir qu'il est très facile à mettre en oeuvre.
Génération de la documentation
Commençons par le commencement : la génération. Si vous utilisez Cargo, rien de plus simple :
> cargo doc
Et c'est tout. Votre documentation se trouvera dans le dossier target/doc/le_nom_de_votre_programme/. Pour l'afficher, ouvrez le fichier index.html qui s'y trouve avec votre navigateur internet préféré, ou lancez la commande :
> cargo doc --open
Maintenant si vous souhaitez le faire sans passer par Cargo :
> rustdoc le_nom_de_votre_fichier_source
Le contenu sera généré dans le dossier ./doc/. Pour consulter la documentation générée, c'est pareil que pour Cargo.
Ajouter des explications
Pour le moment, la documentation que je vous ai fait générer ne contient que du code sans rien d'autre. Pas tip top pour de la doc donc. Au final, ce serait bien qu'on ait une explication, comme ici :
Pour cela, rien de plus simple, il suffit d'utiliser les "///" :
Run/// Et ici je mets la description
/// que je veux !
fn une_fonction() {}
/// Et le markdown aussi fonctionne :
///
/// ```
/// println!("quelque chose");
/// // ou même un exemple d'utilisation de la structure !
/// ```
struct UneStruct {
/// ce champ sert à faire ceci
un_champ: 32,
/// et ce champ sert à faire cela
un_autre_champ: i32
}
Je vous invite maintenant à essayer cela sur vos codes pour voir le résultat obtenu. Il est cependant important de noter que les "///" doivent être mis avant l'objet qu'ils doivent décrire. Ce code ne fonctionnera pas :
Runenum Option<T> {
None,
Some(T), /// Some value `T`
}
Voilà pour les bases.
Documenter un module
Il existe encore un autre niveau de commentaire qui sert à décrire le contenu d'un module, le "//!" ou "/*!". Il doit être mis avant que le code du module ne commence et ne peut être mis qu'une seule fois (par module). Cela donne :
Petit exemple rapide :
Run// copyright
// blablabla
//! Ce module fait ci.
//! Il fait aussi ça.
//!
//! #Titre
//! blabla
//! etc.
// du code...
pub mod un_module {
//! Encore un module !
//! Who dares summon the Rust documentation maker ?!
}
Si vous êtes un peu fainéant, vous pouvez aussi l'écrire de cette façon :
Run// copyright
// blablabla
/*!
Ce module fait ci.
Il fait aussi ça.
#Titre
blabla
etc.
!*/
Cependant, il est plus rare de la voir dans les codes.
Voilà, vous savez maintenant gérer des documentations en Rust !