Test della documentazione
Esempi verificati
Test della documentazione è una lezione Learn Rust Coding gratuita su CoddyKit. Questa è la lezione 4 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.
Cosa sono i doc test?
I doc test sono esempi di codice inseriti nei commenti di documentazione che Cargo compila ed esegue davvero. Mantengono corretta la documentazione e funzionanti gli esempi.
Codice nei commenti di documentazione
Inserite il codice di esempio in un blocco delimitato da tre backtick all'interno di un commento ///, sotto un titolo # Examples. Il linguaggio predefinito è Rust.
/// Doubles a number.
///
/// # Examples
///
/// let result = my_crate::double(4);
/// assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
n * 2
}Eseguire i doc test
I doc test vengono eseguiti come parte di cargo test. Sono riportati separatamente in una sezione Doc-tests.
cargo testAsserzioni negli esempi
Gli esempi includono generalmente asserzioni, così un esempio errato fa fallire il test invece di limitarsi a essere compilato.
/// 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 }
}Nascondere le righe di configurazione
Anteponete # a una riga per eseguirla ma nasconderla nella documentazione visualizzata. È utile per il codice ripetitivo, come gli import.
/// # Examples
///
/// # use my_crate::Counter;
/// let mut c = Counter::new();
/// c.increment();
/// assert_eq!(c.value(), 1);Esempi che usano il punto interrogativo
Per usare l'operatore ?, racchiudete il corpo in un main (o helper) nascosto che restituisce Result. Le righe nascoste iniziano con #.
/// # Examples
///
/// # fn run() -> Result<(), std::num::ParseIntError> {
/// let n: i32 = "42".parse()?;
/// assert_eq!(n, 42);
/// # Ok(())
/// # }Esempi no_run
Contrassegnate un blocco delimitato con l'annotazione no_run per compilarlo senza eseguirlo, utile per gli esempi che richiedono rete o file.
/// 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 e should_panic
Altre annotazioni per il blocco di codice:
ignore— non compila né esegue il codiceshould_panic— indica che è previsto un paniccompile_fail— indica che la compilazione dovrebbe fallire
Perché i doc test sono importanti
I doc test offrono due vantaggi in uno:
- Documentazione sempre accurata
- Copertura di test gratuita per gli esempi pubblici
Se un esempio smette di funzionare, la suite di test fallisce.
Nome del crate negli esempi
I doc test vengono eseguiti come se provenissero dall'esterno del crate, quindi fate riferimento agli elementi tramite il nome del crate, ad esempio my_crate::func, oppure tramite un import use.
Blocchi delimitati e indentati
I doc test accettano due stili di blocco:
- Un blocco delimitato da tre backtick, che consente annotazioni come
no_run - Un blocco indentato di quattro spazi, mostrato in questi esempi
I blocchi delimitati sono più comuni nel codice reale.
Verifica rapida
Cosa fa una riga che inizia con # all'interno di un blocco di codice per doc test?
Riepilogo
Avete imparato a usare i doc test:
- Il codice nei blocchi
///viene compilato ed eseguito dacargo test - Usate le asserzioni per verificare il comportamento
#nasconde le righe di configurazione nella documentazione visualizzata- Annotazioni:
no_run,ignore,should_panic,compile_fail - Mantengono automaticamente corretti gli esempi
Impara Rust con un tutor IA — gratis
Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.
- Corsi
- 39
- Lezioni
- 144
Domande Frequenti
La lezione «Test della documentazione» è gratuita?
Sì — il testo completo di «Test della 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 «Test della documentazione»?
Esempi verificati 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 4 di 4.
Quanto tempo richiede la lezione «Test della 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
- Test unitari
- Test di integrazione
- Commenti di documentazione
- Test della documentazione