Una buona documentazione permette a chi utilizza i nostri progetti di sapere esattamente come procedere per ottenere il lavoro per chi li hanno scelti. In tutti i linguaggi di programmazione c’è un modo per scrivere commenti che non verranno letti dal compilatore ma servono per guidarci.
In Rust non solo possiamo scrivere commenti ed esempi, ma digitando dal terminale cargo doc, avremo tutta la documentazione pronta. Possiamo anche leggere la documentazione delle librerie che abbiamo aggiunto con cargo.
Aggiungere commenti
Come in altri linguaggi, possiamo aggiungere commenti su una singola riga usando i caratteri // mentre i commenti multilinea vanno scritti dentro /* */.
fn main() {
//Questo è un commento su una singola riga
/*
Qui possiamo scrivere più righe
Questa è un'altra riga
*/
println!("Hello World");
}
Aggiungere la documentazione in Rust
Per ogni modulo possiamo aggiungere un commento principale dopo i caratteri //!. Questi commenti appariranno all’inizio della documentazione. Digitando cargo doc verrà generato un file HTML con la documentazione scritta. Se digitiamo cargo doc –open, verrà generato e aperto il file.
I commenti che fanno parte della nostra documentazione vanno inseriti dopo i caratteri ///. Se aggiungiamo a quei caratteri il simbolo del cancelletto # stiamo indicando un sottotitolo. I testi vanno creati dentro “` “`. La documentazione principale va scritta nel file lib.rs.
Esempio in un file o modulo sulla matematica oppure su lib.rs.
//! This is a matematic project
/// Adds two numbers together
/// # Examples
/// ```
/// let sum = add(3, 5);
/// assert_eq!(sum, 8);
/// ```
pub fn add(n1:i32,n2:i32) -> i32 {
n1 + n2
}