Commentaires de documentation
Documentation ///
Commentaires de documentation est une leçon Learn Rust Coding gratuite sur CoddyKit. Ceci est la leçon 3 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.
La documentation en Rust
Rust intègre nativement la documentation au langage. Des commentaires spéciaux deviennent une documentation HTML générée par cargo doc.
Commentaires de documentation externes
Utilisez /// pour documenter l’élément qui le suit — fonctions, structures, énumérations, etc. Le texte accepte le Markdown.
/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
a + b
}Mise en forme Markdown
Les commentaires de documentation sont rendus en Markdown : les titres, les listes, le gras et les liens fonctionnent tous. Le code intégré utilise des accents graves, et les titres de section commencent par #.
/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
width * height
}Sections courantes de la documentation
Des titres conventionnels rendent la documentation plus facile à parcourir :
# Examples— exemples d’utilisation# Panics— situations de panique# Errors— erreurs renvoyées# Safety— invariants du code non sûr
Commentaires de documentation internes
Utilisez //! pour documenter l’élément englobant, généralement un module ou le paquet entier. Placez-le en haut du fichier.
//! # My Math Crate
//!
//! Utilities for basic arithmetic.
pub fn double(n: i32) -> i32 {
n * 2
}Documenter les structures et leurs champs
Chaque élément public, y compris les champs des structures, peut avoir son propre commentaire de documentation.
/// A point in 2D space.
pub struct Point {
/// The horizontal coordinate.
pub x: f64,
/// The vertical coordinate.
pub y: f64,
}Générer la documentation
cargo doc crée la documentation HTML dans target/doc. Ajoutez --open pour l’afficher dans votre navigateur.
cargo doc --openExclure les dépendances
Par défaut, Cargo documente également vos dépendances. Utilisez --no-deps pour générer la documentation de votre seul paquet.
cargo doc --no-deps --openLiens entre éléments de documentation
Créez un lien vers d’autres éléments en écrivant leur chemin entre crochets. Rust résout le chemin et crée un lien cliquable dans la documentation générée.
/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
a - b
}Pourquoi documenter ?
Une bonne documentation est utile :
- Elle est automatiquement générée en HTML consultable
- Elle est publiée gratuitement sur docs.rs lorsque vous publiez un paquet
- Les exemples de la documentation sont testés (tests de documentation)
- Elle aide vos coéquipiers et votre futur vous-même
Documenter un module
Combinez les commentaires internes et externes : un fichier de module commence par //! qui décrit le module, et chaque élément à l’intérieur utilise ///.
//! Geometry helpers.
/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
side * 4.0
}Vérification rapide
Quelle syntaxe de commentaire documente l’élément qui le suit immédiatement ?
Récapitulatif
Vous avez découvert les commentaires de documentation :
///documente l’élément suivant ;//!documente l’élément englobant- Ils acceptent le Markdown et des sections comme
# Examples - Les liens entre éléments relient les différents éléments
cargo doc --opengénère et affiche la documentation HTML
Questions Fréquemment Posées
La leçon « Commentaires de documentation » est-elle gratuite ?
Oui — le texte complet de « Commentaires 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 « Commentaires de documentation » ?
Documentation /// 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 3 sur 4.
Combien de temps prend la leçon « Commentaires 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
- Tests unitaires
- Tests d’intégration
- Commentaires de documentation
- Tests de documentation