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 !