Commenti in Rust

Rust ha un sistema di commenti particolarmente potente: oltre ai commenti classici, supporta commenti di documentazione che vengono trasformati in documentazione HTML con cargo doc.

Commenti su Singola Riga

// Questo è un commento su singola riga
let x = 5; // Commento alla fine della riga

Commenti su Più Righe

/*
Questo è un commento
che si estende su
più righe.
*/

/* I commenti multi-riga /* possono essere annidati */ in Rust */

A differenza di C/C++, i commenti multi-riga in Rust possono essere annidati.

Commenti di Documentazione (///)

I commenti /// documentano l’elemento che li segue e supportano Markdown:

/// Calcola il fattoriale di un numero.
///
/// # Argomenti
///
/// * `n` - Il numero di cui calcolare il fattoriale
///
/// # Esempi
///
/// ```
/// let risultato = fattoriale(5);
/// assert_eq!(risultato, 120);
/// ```
///
/// # Panics
///
/// Causa un panic se `n` è negativo.
pub fn fattoriale(n: u64) -> u64 {
    match n {
        0 | 1 => 1,
        _ => n * fattoriale(n - 1),
    }
}

Commenti di Documentazione del Modulo (//!)

//! documenta l’elemento che li contiene (tipicamente il modulo o il crate):

//! # La mia Libreria Matematica
//!
//! Questa libreria fornisce funzioni matematiche di base
//! per l'uso in applicazioni scientifiche.
//!
//! ## Funzionalità
//!
//! - Calcolo del fattoriale
//! - Numeri di Fibonacci
//! - Operazioni su vettori

pub fn fattoriale(n: u64) -> u64 {
    // ...
}

Sezioni Standard nella Documentazione

/// Breve descrizione della funzione.
///
/// Descrizione più dettagliata che spiega il comportamento.
///
/// # Argomenti
///
/// * `param1` - Descrizione del primo parametro
/// * `param2` - Descrizione del secondo parametro
///
/// # Restituisce
///
/// Descrizione del valore restituito.
///
/// # Errori
///
/// Descrive quando la funzione restituisce `Err`.
///
/// # Panics
///
/// Descrive quando la funzione può causare un panic.
///
/// # Sicurezza
///
/// Per funzioni `unsafe`, descrive le invarianti richieste.
///
/// # Esempi
///
/// ```
/// // Gli esempi vengono compilati e testati con cargo test!
/// let risultato = mia_funzione(1, 2);
/// assert_eq!(risultato, 3);
/// ```
pub fn mia_funzione(param1: i32, param2: i32) -> i32 {
    param1 + param2
}

Generare la Documentazione

# Genera la documentazione HTML
cargo doc

# Genera e apre nel browser
cargo doc --open

# Include anche le dipendenze
cargo doc --document-private-items

Test nella Documentazione

Gli esempi nei commenti /// vengono automaticamente compilati e testati con cargo test:

/// Somma due numeri.
///
/// ```
/// assert_eq!(somma(2, 3), 5);
/// assert_eq!(somma(-1, 1), 0);
/// ```
pub fn somma(a: i32, b: i32) -> i32 {
    a + b
}

Esegui i doc-test con cargo test --doc.

Conclusione

Il sistema di documentazione di Rust è tra i migliori in qualsiasi linguaggio di programmazione. I commenti /// con supporto Markdown, gli esempi testabili automaticamente e cargo doc rendono naturale mantenere la documentazione aggiornata e affidabile. Documenta sempre le API pubbliche dei tuoi crate.