Learn Rust Coding · Leçon

Tests de documentation

Exemples testés

Tests de documentation est une leçon Learn Rust Coding gratuite sur CoddyKit. Ceci est la leçon 4 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage Learn Rust Coding, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours Learn Rust Coding comprend 4 leçons au total.

Que sont les tests de documentation ?

Les tests de documentation sont des exemples de code placés dans les commentaires de documentation que Cargo compile et exécute réellement. Ils garantissent que votre documentation reste correcte et que vos exemples fonctionnent.

Code dans les commentaires de documentation

Placez le code d’exemple dans un bloc de code délimité par trois accents graves, à l’intérieur d’un commentaire ///, sous un titre # Examples. Le langage par défaut est Rust.

/// Doubles a number.
///
/// # Examples
///
///     let result = my_crate::double(4);
///     assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
    n * 2
}

Exécuter les tests de documentation

Les tests de documentation sont exécutés dans le cadre de cargo test. Ils sont présentés séparément dans une section Doc-tests.

cargo test

Assertions dans les exemples

Les exemples contiennent généralement des assertions afin qu’un exemple incorrect fasse échouer le test, au lieu de simplement compiler.

/// Returns the larger of two values.
///
/// # Examples
///
///     assert_eq!(my_crate::max(3, 7), 7);
///     assert_eq!(my_crate::max(9, 2), 9);
pub fn max(a: i32, b: i32) -> i32 {
    if a > b { a } else { b }
}

Masquer des lignes de préparation

Faites précéder une ligne de # pour l’exécuter tout en la masquant dans la documentation affichée. C’est utile pour le code répétitif, comme les imports.

/// # Examples
///
///     # use my_crate::Counter;
///     let mut c = Counter::new();
///     c.increment();
///     assert_eq!(c.value(), 1);

Exemples utilisant le point d’interrogation

Pour utiliser l’opérateur ?, placez le corps dans un main masqué (ou un utilitaire) qui renvoie Result. Les lignes masquées commencent par #.

/// # Examples
///
///     # fn run() -> Result<(), std::num::ParseIntError> {
///     let n: i32 = "42".parse()?;
///     assert_eq!(n, 42);
///     # Ok(())
///     # }

Exemples no_run

Marquez un bloc délimité avec l’annotation no_run pour le compiler sans l’exécuter — pratique pour les exemples qui nécessitent le réseau ou des fichiers.

/// Fetches a page (compiled but not executed).
///
/// Annotate the code fence with no_run so it is type-checked only.
pub fn fetch(url: &str) -> String {
    format!("contents of {url}")
}

ignore et should_panic

Autres annotations du bloc de code :

ignore — ni compilé ni exécuté
should_panic — une panique est attendue
compile_fail — la compilation doit échouer

Pourquoi les tests de documentation sont importants

Les tests de documentation vous offrent deux avantages à la fois :

Une documentation toujours exacte
Une couverture de test gratuite pour vos exemples publics

Si un exemple ne fonctionne plus, la suite de tests échoue.

Nom du paquet dans les exemples

Les tests de documentation sont exécutés comme s’ils provenaient de l’extérieur du paquet ; référencez donc les éléments avec le nom du paquet (par exemple my_crate::func) ou avec un import use.

Blocs délimités ou indentés

Les tests de documentation acceptent deux styles de blocs :

Un bloc délimité par trois accents graves, qui permet des annotations comme no_run
Un bloc indenté de quatre espaces, utilisé dans ces exemples

Les blocs délimités sont plus courants dans le code réel.

Vérification rapide

Que fait une ligne commençant par # dans un bloc de code de test de documentation ?

Récapitulatif

Vous avez découvert les tests de documentation :

Le code des blocs /// est compilé et exécuté par cargo test
Utilisez des assertions pour vérifier le comportement
# masque les lignes de préparation dans la documentation affichée
Annotations : no_run, ignore, should_panic, compile_fail
Elles garantissent automatiquement que les exemples restent corrects

Questions Fréquemment Posées

La leçon « Tests de documentation » est-elle gratuite ?

Oui — le texte complet de « Tests de documentation » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours Learn Rust Coding, passe à CoddyKit PRO. Le cours Learn Rust Coding comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Tests de documentation » ?

Exemples testés Tu pratiques Learn Rust Coding avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer Learn Rust Coding ?

Aucune expérience préalable n'est requise. Learn Rust Coding sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 4 sur 4.

Combien de temps prend la leçon « Tests de documentation » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon Learn Rust Coding ?

Oui. Chaque leçon Learn Rust Coding inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à Learn Rust Coding