Rustdoc : Guide du débutant pour la documentation d'API en Rust

La documentation sert de pont entre les développeurs et les utilisateurs de leur code. Dans l'écosystème Rust, la documentation est élevée au rang de citoyen de premier ordre grâce à Rustdoc, un outil sophistiqué de génération de documentation fourni avec la distribution standard de Rust. Contrairement aux outils de documentation de nombreux autres langages, Rustdoc ne se contente pas de générer une documentation statique, il crée des sites Web de documentation interactifs, testables et richement formatés qui améliorent la découvrabilité et la convivialité du code.

Pour les développeurs Rust, Apidog offre des fonctionnalités complètes de documentation d'API pour les API HTTP avec des capacités de test interactives, un formatage visuel des réponses et des fonctions collaboratives.

Apidog se concentre sur la documentation des points de terminaison, des formats de requête/réponse et des spécifications HTTP, Rustdoc se spécialise dans la documentation du code au niveau du langage, en documentant les structs, les fonctions, les traits et autres constructions de programmation qui composent un crate Rust. Les deux systèmes partagent l'objectif fondamental de rendre les systèmes techniques complexes plus accessibles grâce à une documentation complète, précise et utilisable.

Qu'est-ce que Rustdoc ?

Rustdoc est un outil en ligne de commande qui analyse le code source Rust et les commentaires de documentation spéciaux pour générer des fichiers HTML, CSS et JavaScript qui forment un site Web de documentation consultable. À la base, Rustdoc fonctionne en extrayant les commentaires de documentation de votre code et en les transformant en documentation structurée.

Le fonctionnement de base de Rustdoc implique :

1. L'analyse des fichiers sources Rust pour extraire les commentaires de documentation
2. La conversion de ces commentaires de Markdown en HTML
3. La génération d'une structure de site Web consultable et navigable
4. L'extraction d'exemples de code de la documentation et leur préparation pour les tests
5. La création de références croisées entre les éléments
6. La production d'actifs statiques pour la documentation finale

Lorsqu'il est appelé directement, le binaire Rustdoc accepte un fichier source Rust en entrée :

$ rustdoc src/lib.rs --crate-name my_crate

Cette commande traite le fichier lib.rs et génère une documentation dans un répertoire doc par défaut. La documentation est structurée hiérarchiquement, reflétant la structure de votre code, avec des pages distinctes pour les modules, les structs, les enums, les traits et autres constructions Rust.

Sous le capot, Rustdoc exploite les API internes du compilateur Rust pour analyser et comprendre votre code. Cette intégration étroite avec le compilateur permet à Rustdoc de générer des références croisées précises, de documenter correctement les signatures de type et de vérifier que les exemples de code se compilent et s'exécutent correctement.

Commentaires de documentation en Rust

La documentation en Rust repose sur une syntaxe de commentaire spéciale qui diffère des commentaires de code réguliers. Il existe deux principaux types de commentaires de documentation :

Commentaires de documentation externes (///)

Les commentaires de documentation externes documentent l'élément qui les suit et sont désignés par trois barres obliques :

/// Ceci est un commentaire de documentation pour la fonction ci-dessous.
/// Il peut s'étendre sur plusieurs lignes et prend en charge le formatage Markdown.
pub fn documented_function() -> bool {
    true
}

Ces commentaires décrivent les fonctions, les structs, les enums, les traits, les modules et autres éléments de votre base de code. Ils sont appelés documentation "externe" car ils existent en dehors de l'élément qu'ils documentent.

Commentaires de documentation internes (//!)

Les commentaires de documentation internes documentent l'élément dans lequel ils apparaissent et sont désignés par //! :

//! Ce module fournit des utilitaires pour l'analyse des fichiers de configuration.
//!
//! # Exemples
//!
//! ```
//! let config = my_crate::config::parse("config.toml");
//! assert!(config.is_ok());
//! ```

pub fn parse(file_path: &str) -> Result<Config, ParseError> {
    // Implémentation ici
}

Les commentaires de documentation internes sont couramment utilisés pour la documentation au niveau du module ou du crate. Lorsqu'ils sont placés au début d'un fichier lib.rs, ils documentent l'ensemble du crate et forment la page d'accueil de votre documentation générée.

La différence technique entre ces styles de commentaires est subtile mais importante : /// documente ce qui le suit, tandis que //! documente ce qui le contient.

Prise en charge de Markdown dans Rustdoc

Rustdoc utilise un analyseur Markdown conforme à CommonMark avec plusieurs extensions. Cela donne aux auteurs de documentation accès à un riche ensemble d'options de formatage :

Formatage de base

/// # Titre de niveau 1
/// ## Titre de niveau 2
///
/// Les paragraphes sont séparés par des lignes vides.
///
/// *Texte en italique* et **texte en gras** sont pris en charge.
///
/// - Listes non ordonnées
/// - Peuvent être créées
/// - Comme ceci
///
/// 1. Listes ordonnées
/// 2. Fonctionnent également
///
/// `Code en ligne` est entouré d'accents graves.

Blocs de code

Les blocs de code sont particulièrement importants dans Rustdoc car ils servent à deux fins : ils affichent des exemples de code dans la documentation et peuvent être extraits en tant que tests.

/// ```rust
/// // Ceci est un bloc de code
/// let x = 5;
/// assert_eq!(x, 5);
/// ```

Par défaut, si aucune langue n'est spécifiée après les trois accents graves ouvrants, Rustdoc suppose que le bloc de code contient du code Rust. Cependant, vous pouvez spécifier d'autres langues pour la coloration syntaxique :

/// ```json
/// {
///     "name": "example",
///     "version": "1.0.0"
/// }
/// ```

Extensions Rustdoc

Rustdoc étend CommonMark avec plusieurs fonctionnalités supplémentaires :

Texte barré

/// ~~Texte barré~~ utilise des tildes.

Notes de bas de page

/// Cette déclaration nécessite des éclaircissements[^1].
///
/// [^1]: Voici les éclaircissements.

Tableaux

/// | En-tête1 | En-tête2 |
/// |---------|---------|
/// | cellule1   | cellule2   |
/// | cellule3   | cellule4   |

Listes de tâches

/// - [x] Tâche terminée
/// - [ ] Tâche incomplète

Ponctuation intelligente

Rustdoc convertit automatiquement les séquences de ponctuation ASCII en leurs équivalents Unicode :

• -- devient un tiret cadratin (–)
• --- devient un tiret cadratin (—)
• ... devient des points de suspension (…)
• Les guillemets droits deviennent des guillemets courbes

Interface en ligne de commande détaillée de Rustdoc

Rustdoc offre un ensemble complet d'options de ligne de commande pour personnaliser la génération de documentation :

$ rustdoc --help

Certaines des options les plus importantes sur le plan technique incluent :

• --document-private-items : Par défaut, Rustdoc ne documente que les éléments publics. Cet indicateur inclut les éléments privés dans la documentation, ce qui est utile pour la documentation interne.
• --test : Exécute les exemples de documentation en tant que tests, en vérifiant qu'ils se compilent et s'exécutent comme prévu.
• --test-args : Transmet des arguments supplémentaires au programme d'exécution des tests, tels que --nocapture pour afficher la sortie des tests.
• --edition=EDITION : Spécifiez l'édition Rust pour l'analyse et l'exécution du code (2015, 2018, 2021, 2024).
• --target=TARGET : Génère une documentation pour la plateforme cible spécifiée.
• --crate-type=TYPE : Spécifiez le type de crate pour les tests (bin, lib, rlib, dylib, cdylib, staticlib, proc-macro).
• -L FLAG=PATH : Ajoutez un répertoire au chemin de recherche de la bibliothèque, ce qui est crucial pour la résolution des dépendances dans les tests.
• --cfg=SPEC : Transmettez un indicateur --cfg au compilateur, ce qui permet la compilation conditionnelle dans le code de documentation.
• --extern NAME=PATH : Spécifiez l'emplacement d'un crate externe, ce qui permet aux tests de référencer des dépendances externes.

Pour un projet avec des dépendances externes, une invocation Rustdoc typique pourrait ressembler à ceci :

$ rustdoc src/lib.rs --crate-name example_crate \
  --edition=2021 \
  -L dependency=target/debug/deps \
  --extern serde=target/debug/deps/libserde-abcd1234.rlib \
  --extern tokio=target/debug/deps/libtokio-efgh5678.rlib

Heureusement, Cargo automatise ce processus complexe avec une simple commande :

$ cargo doc --document-private-items

Intégration avec Cargo

Cargo fournit une interface simplifiée pour travailler avec Rustdoc via la commande cargo doc. En interne, Cargo appelle Rustdoc avec les paramètres appropriés :

$ cargo doc --verbose

L'exécution de cette commande affichera l'invocation réelle de Rustdoc, révélant comment Cargo configure les chemins vers les dépendances et les répertoires de sortie.

Les fonctionnalités de base incluent :

• cargo doc : Générer une documentation pour le crate actuel et ses dépendances
• cargo doc --no-deps : Générer une documentation uniquement pour le crate actuel
• cargo doc --open : Générer une documentation et l'ouvrir dans un navigateur Web
• cargo doc --document-private-items : Inclure les éléments privés dans la documentation
• cargo test --doc : Exécuter les tests de documentation

Cargo détermine intelligemment le nom du crate à partir de votre fichier Cargo.toml, configure la structure de répertoire de sortie correcte sous target/doc/ et s'assure que toutes les dépendances sont correctement liées.

Structure et organisation de la documentation

Documentation au niveau du crate

La documentation au niveau du crate sert de page d'accueil pour votre bibliothèque et doit fournir une vue d'ensemble complète. Ceci est écrit en tant que documentation interne (//!) en haut du fichier lib.rs :

//! # Ma bibliothèque de cryptographie avancée
//!
//! Ce crate fournit des primitives cryptographiques en mettant l'accent sur :
//!
//! - **Performance** : Mises en œuvre optimisées pour les processeurs modernes
//! - **Sécurité** : Algorithmes formellement vérifiés
//! - **Convivialité** : API de haut niveau, difficiles à mal utiliser
//!
//! ## Démarrage rapide
//!
//! ```rust
//! use crypto_lib::{Cipher, Mode};
//!
//! let key = crypto_lib::generate_key(256);
//! let cipher = Cipher::new(&key, Mode::GCM);
//!
//! let plaintext = b"Secret message";
//! let ciphertext = cipher.encrypt(plaintext);
//! ```
//!
//! ## Fonctionnalités
//!
//! Le crate prend en charge les algorithmes suivants :
//!
//! - AES (128, 192, 256)
//! - ChaCha20
//! - Poly1305
//! - HMAC
//! - PBKDF2

Une documentation efficace au niveau du crate comprend souvent :

1. Une description concise d'une phrase de l'objectif du crate
2. Une explication détaillée des concepts et des fonctionnalités clés
3. Des exemples de démarrage rapide montrant une utilisation de base
4. Une vue d'ensemble de l'architecture pour les bibliothèques plus complexes
5. Des indicateurs de fonctionnalités et des options de configuration
6. Des informations de compatibilité
7. Des caractéristiques de performance

Documentation au niveau du module

Les modules agissent comme des unités organisationnelles en Rust et doivent avoir leur propre documentation qui explique leur objectif et leur contenu :

pub mod symmetric {
    //! Algorithmes de chiffrement symétriques.
    //!
    //! Ce module fournit des implémentations de chiffrements par blocs et par flux,
    //! des algorithmes de chiffrement authentifiés et des utilitaires connexes.
    //!
    //! # Considérations de sécurité
    //!
    //! Toutes les implémentations ont été auditées par [Security Firm]
    //! et formellement vérifiées à l'aide de [Verification Tool].

    /// Implémentation du chiffrement par blocs AES avec prise en charge des clés de 128, 192 et 256 bits.
    pub struct Aes {
        // Champs ici
    }

    // Plus d'éléments...
}

Documentation au niveau de l'élément

Les éléments individuels comme les structs, les fonctions et les traits doivent avoir une documentation ciblée qui explique leur objectif, leur utilisation et toute considération particulière :

/// Un générateur de nombres aléatoires cryptographiquement sécurisé.
///
/// Ce CSPRNG utilise la source d'entropie du système pour générer
/// des octets aléatoires adaptés aux opérations cryptographiques.
///
/// # Exemples
///
/// ```
/// use crypto_lib::CSPRNG;
///
/// let mut rng = CSPRNG::new();
/// let random_bytes = rng.generate_bytes(32);
/// ```
///
/// # Sécurité
///
/// Sur Linux, cela utilise getrandom(2) lorsqu'il est disponible, en revenant à /dev/urandom.
/// Sur Windows, il utilise BCryptGenRandom.
/// Sur macOS, il utilise SecRandomCopyBytes.
pub struct CSPRNG {
    // Détails de l'implémentation
}

impl CSPRNG {
    /// Crée un nouveau générateur de nombres aléatoires cryptographiquement sécurisé.
    ///
    /// # Paniques
    ///
    /// Panique si la source d'entropie du système n'est pas disponible.
    ///
    /// # Exemples
    ///
    /// ```
    /// let rng = crypto_lib::CSPRNG::new();
    /// ```
    pub fn new() -> Self {
        // Implémentation
    }

    /// Génère le nombre spécifié d'octets aléatoires.
    ///
    /// # Arguments
    ///
    /// * `len` - Le nombre d'octets aléatoires à générer
    ///
    /// # Retours
    ///
    /// Un vecteur contenant `len` octets aléatoires cryptographiquement sécurisés.
    ///
    /// # Exemples
    ///
    /// ```
    /// use crypto_lib::CSPRNG;
    ///
    /// let mut rng = CSPRNG::new();
    /// let key_material = rng.generate_bytes(32);
    /// assert_eq!(key_material.len(), 32);
    /// ```
    pub fn generate_bytes(&mut self, len: usize) -> Vec<u8> {
        // Implémentation
    }
}

Tests de documentation en profondeur

L'une des fonctionnalités les plus puissantes de Rustdoc est sa capacité à exécuter des exemples de code en tant que tests. Cela garantit que :

1. Les exemples de votre documentation se compilent réellement
2. Les exemples produisent les résultats attendus
3. Les exemples restent à jour à mesure que votre API évolue

Lorsque vous incluez un bloc de code Rust dans votre documentation, Rustdoc l'extrait et crée un harnais de test autour de celui-ci :

/// Ajoute deux nombres.
///
/// # Exemples
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

En coulisses, Rustdoc transforme cela en un fichier de test autonome ressemblant à :

extern crate my_crate;

fn main() {
    let result = my_crate::add(2, 3);
    assert_eq!(result, 5);
}

Ce fichier est ensuite compilé et exécuté. Si le programme se compile et s'exécute sans paniquer, le test réussit.

Prétraitement des tests

Avant d'exécuter le test, Rustdoc applique plusieurs transformations pour rendre les exemples simples plus ergonomiques :

1. Les lints courants comme unused_variables et dead_code sont autorisés
2. Si l'exemple ne contient pas extern crate et que #![doc(test(no_crate_inject))] n'a pas été spécifié, extern crate <mycrate>; est inséré
3. Si l'exemple ne contient pas fn main, le code est encapsulé dans fn main() { ... }

Ces transformations vous permettent de vous concentrer sur les parties importantes de votre exemple sans code réutilisable.

Contrôle du comportement des tests

Rustdoc fournit plusieurs attributs pour contrôler la façon dont les tests sont exécutés :

• ignore : Le code n'est pas testé
• should_panic : Le code doit se compiler mais paniquer lors de l'exécution
• compile_fail : Le code ne doit pas se compiler
• no_run : Le code est compilé mais pas exécuté
• edition2015, edition2018, edition2021 : Exécutez le code avec une édition Rust spécifique

Exemples :

/// ```ignore
/// // Ce code n'est pas testé
/// let x = function_that_doesnt_exist();
/// ```
///
/// ```should_panic
/// // Ce code doit paniquer
/// panic!("Cet exemple démontre une panique");
/// ```
///
/// ```compile_fail
/// // Ce code ne doit pas se compiler
/// let x: i32 = "this should not compile";
/// ```
///
/// ```no_run
/// // Ce code se compile mais ne s'exécute pas
/// loop {
///     println!("Cela s'exécuterait pour toujours !");
/// }
/// ```
///
/// ```edition2021
/// // Ce code utilise les fonctionnalités de Rust 2021
/// let result = try {
///     "10".parse::<i32>()?
/// };
/// ```

Utilisation de ? dans les tests de documents

Étant donné que les exemples de documentation sont encapsulés dans une fonction main() qui renvoie (), l'utilisation de l'opérateur ? nécessite une gestion spéciale. Il existe deux approches :

1. Définir explicitement une fonction main qui renvoie un Result :

/// ```
/// # fn main() -> Result<(), std::io::Error> {
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("File content: {}", content);
/// # Ok(())
/// # }
/// ```

2. Utilisez une annotation de type avec Ok(()) :

/// ```
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("File content: {}", content);
/// # Ok::<(), std::io::Error>(())
/// ```

Dans les deux cas, le # au début de certaines lignes les masque de la documentation rendue, mais les inclut dans le test.

Lien vers des éléments par nom

Rustdoc fournit un puissant système de références croisées qui permet aux auteurs de documentation de créer des liens vers d'autres éléments de la base de code. Cette fonctionnalité améliore considérablement la navigabilité de votre documentation.

Liens intra-doc

Pour créer un lien vers un autre élément, utilisez la syntaxe [nom_élément] :

/// Utilise le type [`HashMap`] de la bibliothèque standard.
///
/// Il s'appuie également sur la fonction [`build_map`] définie ailleurs dans ce crate.
pub fn process_data() {
    // Implémentation
}

/// Construit un nouveau [`HashMap`] avec des valeurs prédéfinies.
pub fn build_map() -> HashMap<String, i32> {
    // Implémentation
}

Lorsque Rustdoc traite ces liens, il les résout automatiquement vers les éléments corrects, créant des hyperliens cliquables dans le HTML généré.

Qualification de chemin

Pour un lien plus précis, en particulier lorsque vous traitez des éléments qui pourraient avoir le même nom dans différents modules, vous pouvez utiliser des chemins complets :

/// Cette fonction utilise [`std::collections::HashMap`] pour le stockage
/// et [`crate::utils::format`] pour le formatage de la sortie.
pub fn complex_operation() {
    // Implémentation
}

La résolution du chemin suit les règles de visibilité de Rust, vous ne pouvez donc créer des liens que vers des éléments qui seraient visibles à partir de la portée actuelle.

Cibles de liens

Vous pouvez créer des liens vers différents types d'éléments :

/// Liens vers une struct : [`MyStruct`]
/// Liens vers un enum : [`Option`]
/// Liens vers un trait : [`Iterator`]
/// Liens vers une fonction : [`process_data`]
/// Liens vers une méthode : [`MyStruct::new`]
/// Liens vers un module : [`crate::utils`]
/// Liens vers une constante : [`MAX_SIZE`]
/// Liens vers un alias de type : [`Result`]

Ce système de liens complet permet aux auteurs de documentation de créer un riche réseau de documentation interconnectée qui aide les utilisateurs à naviguer dans les API complexes.

Fonctionnalités de documentation avancées

L'attribut #[doc]

L'attribut #[doc] fournit un contrôle avancé sur la génération de documentation :

// Équivalent à l'utilisation de commentaires ///
#[doc = "Ceci est la documentation de l'élément ci-dessous."]
pub struct DocumentedStruct;

// Masquer un élément de la documentation
#[doc(hidden)]
pub struct InternalStruct;

// Ajouter des alias de recherche
#[doc(alias = "connection")]
#[doc(alias = "socket")]
pub struct NetworkStream;

Pour une documentation conditionnelle basée sur des indicateurs de fonctionnalités :

/// Cette fonction fait des choses incroyables.
#[doc = "Explication des capacités de base."]
#[cfg_attr(feature = "advanced", doc = "Prend également en charge le mode avancé lorsque la fonctionnalité 'advanced' est activée.")]
pub fn do_things() {
    // Implémentation
}

Modèles d'inclusion de documentation

Pour réutiliser du contenu dans la documentation :

/// # Sécurité
///
#[doc = include_str!("../docs/common_safety_notes.md")]
pub unsafe fn perform_unsafe_operation() {
    // Implémentation
}

Cela vous permet de conserver des segments de documentation communs dans des fichiers séparés et de les inclure là où cela est nécessaire, ce qui réduit la duplication et garantit la cohérence.

Exemples extraits

Rustdoc peut automatiquement extraire des exemples de code des répertoires de tests et d'exemples de votre crate, fournissant un contexte supplémentaire pour l'utilisation de l'API :

$ cargo doc --document-scraped-examples

Cette fonctionnalité fonctionne en analysant votre crate à la recherche de l'utilisation d'éléments publics et en extrayant ces utilisations en tant qu'exemples. Elle est particulièrement précieuse pour les API complexes où les exemples de documentation en ligne pourraient être insuffisants.

Documentation conditionnelle

En utilisant les attributs cfg, vous pouvez inclure ou exclure conditionnellement la documentation :

#[cfg(target_os = "windows")]
/// Détails d'implémentation spécifiques à Windows.
pub fn windows_only_function() {
    // Implémentation Windows
}

#[cfg(target_os = "linux")]
/// Détails d'implémentation spécifiques à Linux.
pub fn linux_only_function() {
    // Implémentation Linux
}

Cela vous permet de créer une documentation spécifique à la plateforme ou à la fonctionnalité qui n'apparaît que lorsque cela est pertinent.

HTML personnalisé dans la documentation

Pour des besoins de formatage spéciaux, Rustdoc permet d'intégrer du HTML directement dans la documentation :

/// <div class="warning">
/// <strong>Avertissement :</strong> Cette fonction effectue des E/S et peut bloquer.
/// </div>
pub fn blocking_operation() {
    // Implémentation
}

Combiné avec le CSS personnalisé, cela permet un formatage riche au-delà de ce que Markdown seul fournit.

HTML et CSS personnalisés

Rustdoc permet la personnalisation de l'apparence de la documentation générée via HTML et CSS :

Prétraitement HTML

Vous pouvez ajouter du HTML personnalisé à l'en-tête de la documentation :

$ rustdoc src/lib.rs --html-in-header custom-header.html

Ceci est utile pour ajouter des feuilles de style personnalisées, des bibliothèques JavaScript ou des balises meta.

Personnalisation CSS

Pour appliquer un CSS personnalisé à votre documentation :

$ rustdoc src/lib.rs --css custom-styles.css

Votre fichier CSS peut cibler la structure HTML de Rustdoc pour personnaliser les couleurs, les polices, les mises en page, etc. :

/* Changer la couleur de fond principale */
body {
    background-color: #f5f5f5;
}

/* Style des blocs d'avertissement */
.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 0.5rem 1rem;
    margin: 1rem 0;
}

/* Style personnalisé pour les blocs de code */
pre {
    background-color: #282c34;
    border-radius: 6px;
    padding: 1rem;
}

Thèmes de rendu personnalisés

Rustdoc prend en charge plusieurs thèmes intégrés, notamment Light, Rust, Coal, Navy et Ayu. Vous pouvez également créer des thèmes personnalisés :

$ rustdoc src/lib.rs --theme mytheme.css

Meilleures pratiques en matière de documentation

Précision technique

La documentation doit être techniquement précise. Spécifiez le comportement exact, les cas limites et les caractéristiques de performance :

/// Recherche un élément dans une tranche triée à l'aide d'une recherche binaire.
///
/// # Complexité
///
/// Complexité temporelle : O(log n)
/// Complexité spatiale : O(1)
///
/// # Paniques
///
/// Panique si la tranche n'est pas triée par ordre croissant.
///
/// # Exemples
///
/// ```
/// let sorted = [1, 2, 3, 4, 5];
/// assert_eq!(my_crate::binary_search(&sorted, 3), Some(2));
/// assert_eq!(my_crate::binary_search(&sorted, 6), None);
/// ```
pub fn binary_search<T: Ord>(slice: &[T], value: T) -> Option<usize> {
    // Implémentation
}

Documentation structurée

Suivez une structure cohérente pour chaque type d'élément :

Fonctions et méthodes :

• Brève description
• Explications des paramètres
• Description de la valeur de retour
• Cas d'erreur
• Section Paniques (le cas échéant)
• Exemples
• Caractéristiques de performance
• Considérations de sécurité (pour les fonctions unsafe)

Structs et enums :

• Objectif et description de haut niveau
• Explications des champs/variantes
• Méthodes de construction
• Opérations courantes
• Exemples d'utilisation typique

Traits :

• Contrat et garanties
• Explication des méthodes requises
• Documentation des méthodes fournies
• Conseils d'implémentation
• Exemples montrant l'implémentation et l'utilisation

Précision du langage

Utilisez un langage technique précis et évitez l'ambiguïté :

• Au lieu de "rapide", spécifiez "complexité temporelle O(log n)"
• Au lieu de "efficace en mémoire", spécifiez "utilise un espace de pile constant"
• Au lieu de "pourrait échouer", spécifiez les conditions d'erreur exactes
• Au lieu de "entrées volumineuses", spécifiez les limitations concrètes

Informations sur le versioning

Documentez la stabilité de l'API et les considérations de versioning :

/// Traite les paquets réseau conformément à la RFC 1234.
///
/// # Stabilité
///
/// Cette fonction est considérée comme stable depuis la version 0.2.0.
///
/// # Différences de version
///
/// Avant la version 0.3.0, cette fonction tronquait silencieusement