Learn Rust Coding · Lezione

Commenti di documentazione

Documentazione con ///

Commenti di documentazione è una lezione Learn Rust Coding gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Learn Rust Coding, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Learn Rust Coding include 4 lezioni in totale.

Documentazione in Rust

Rust integra la documentazione direttamente nel linguaggio. Commenti speciali diventano documentazione HTML generata da cargo doc.

Commenti di documentazione esterni

Usate /// per documentare l'elemento che lo segue: funzioni, struct, enum e altro. Il testo supporta Markdown.

/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Formattazione Markdown

I commenti di documentazione vengono elaborati come Markdown: funzionano titoli, elenchi, testo in grassetto e link. Il codice inline usa i backtick e i titoli delle sezioni iniziano con #.

/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
    width * height
}

Sezioni comuni della documentazione

I titoli convenzionali rendono la documentazione facile da consultare:

# Examples — esempi d'uso
# Panics — quando si verifica un panic
# Errors — quali errori vengono restituiti
# Safety — invarianti per il codice unsafe

Commenti di documentazione interni

Usate //! per documentare l'elemento contenitore, in genere un modulo o l'intero crate. Inseritelo all'inizio del file.

//! # My Math Crate
//!
//! Utilities for basic arithmetic.

pub fn double(n: i32) -> i32 {
    n * 2
}

Documentare struct e campi

Ogni elemento pubblico, inclusi i campi delle struct, può avere il proprio commento di documentazione.

/// A point in 2D space.
pub struct Point {
    /// The horizontal coordinate.
    pub x: f64,
    /// The vertical coordinate.
    pub y: f64,
}

Generare la documentazione

cargo doc crea la documentazione HTML nella directory target/doc. Aggiungete --open per visualizzarla nel browser.

cargo doc --open

Escludere le dipendenze

Per impostazione predefinita, Cargo documenta anche le dipendenze. Usate --no-deps per generare la documentazione solo del vostro crate.

cargo doc --no-deps --open

Link intra-documentazione

Collegatevi ad altri elementi scrivendone il percorso tra parentesi quadre. Rust risolve il percorso e crea un link cliccabile nella documentazione generata.

/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

Perché documentare?

Una buona documentazione offre molti vantaggi:

Viene generata automaticamente in HTML ricercabile
Viene pubblicata gratuitamente su docs.rs quando pubblicate un crate
Gli esempi nella documentazione vengono testati (doc test)
Aiuta i colleghi e anche voi in futuro

Documentare un modulo

Combinate commenti interni ed esterni: il file del modulo inizia con //! per descrivere il modulo, mentre ogni elemento al suo interno usa ///.

//! Geometry helpers.

/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
    side * 4.0
}

Verifica rapida

Quale sintassi di commento documenta l'elemento immediatamente successivo?

Riepilogo

Avete imparato a usare i commenti di documentazione:

/// documenta l'elemento successivo; //! documenta l'elemento contenitore
Supportano Markdown e sezioni come # Examples
I link intra-documentazione collegano gli elementi
cargo doc --open genera e visualizza la documentazione HTML

Domande Frequenti

La lezione «Commenti di documentazione» è gratuita?

Sì — il testo completo di «Commenti di documentazione» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Learn Rust Coding, passa a CoddyKit PRO. Il corso Learn Rust Coding include 4 lezioni in totale.

Cosa imparerò in «Commenti di documentazione»?

Documentazione con /// Eserciti Learn Rust Coding con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Learn Rust Coding?

Non è richiesta alcuna esperienza precedente. Learn Rust Coding su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Commenti di documentazione»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Learn Rust Coding?

Sì. Ogni lezione Learn Rust Coding include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a Learn Rust Coding