III. Aller plus loin

3. Documentation et rustdoc

En plus du compilateur, Rust possède un générateur de documentation. Toute la documentation en ligne de la bibliothèque standard (disponible ici) a été générée avec cet outil. Vous allez voir qu'il est très facile de s'en servir.

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 utilisez 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.

Il est important de noter que rustdoc accepte aussi les fichiers markdown (.md) comme argument :

> rustdoc fichier.md

Cela créera un fichier ./doc/fichier.html.

Ajouter de la documentation

Pour le moment, la documentation que je vous ai fait générer ne contient que du code sans rien d'autre. Pas génial pour de la documentation donc... Au final, ce serait bien qu'on ait des explications sur les items, comme ici :

Pour cela, rien de plus simple, il suffit d'utiliser les "///" (aussi appelé "doc comments") :

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
}

La documentation en Rust utilise le format commonmark (qui est une spécification du markdown). Donc vous pouvez ajouter du style sans problème. Par-exemple :

Run/// _italique_ *italique aussi*
/// _gras_ **gras aussi**
/// `code inline`
/// # Gros titre
/// # Titre plus petit

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 documenter. 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 "/*!". Cela fonctionne de la même façon que les autres attributs de modules (car après tout, les doc comments sont des attributs) : cela doit être mis en premier, avant des déclarations d'items.

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 ! Il reste cependant un point que nous n'avons pas abordé : il est possible d'ajouter des exemples de codes qui seront testés directement dans votre documentation. Nous allons en parler dans le prochain chapitre.