Learn Rust Coding · Aula

Testes de documentação

Exemplos testados

Testes de documentação é uma aula grátis de Learn Rust Coding no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Learn Rust Coding, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Learn Rust Coding inclui 4 aulas no total.

O que são testes de documentação?

Os testes de documentação são exemplos de código dentro de comentários de documentação que o Cargo realmente compila e executa. Eles mantêm sua documentação correta e seus exemplos funcionando.

Código em comentários de documentação

Coloque o código de exemplo em um bloco de código delimitado por três crases dentro de um comentário ///, sob um título # Examples. A linguagem padrão é Rust.

/// Doubles a number.
///
/// # Examples
///
///     let result = my_crate::double(4);
///     assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
    n * 2
}

Executando testes de documentação

Os testes de documentação são executados como parte de cargo test. Eles são informados separadamente em uma seção Doc-tests.

cargo test

Asserções em exemplos

Os exemplos geralmente incluem asserções para que um exemplo incorreto faça o teste falhar, em vez de apenas compilar.

/// 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 }
}

Ocultando linhas de configuração

Prefixe uma linha com # para executá-la, mas ocultá-la na documentação renderizada. Isso é útil para código repetitivo, como importações.

/// # Examples
///
///     # use my_crate::Counter;
///     let mut c = Counter::new();
///     c.increment();
///     assert_eq!(c.value(), 1);

Exemplos usando o ponto de interrogação

Para usar o operador ?, envolva o corpo em um main (ou auxiliar) oculto que retorne Result. As linhas ocultas começam com #.

/// # Examples
///
///     # fn run() -> Result<(), std::num::ParseIntError> {
///     let n: i32 = "42".parse()?;
///     assert_eq!(n, 42);
///     # Ok(())
///     # }

Exemplos no_run

Marque um bloco delimitado com a anotação no_run para compilá-lo, mas não executá-lo — útil para exemplos que precisam de rede ou arquivos.

/// 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

Outras anotações para o bloco de código:

ignore — não compila nem executa
should_panic — espera-se que entre em pânico
compile_fail — espera-se que não compile

Por que os testes de documentação são importantes

Os testes de documentação trazem dois benefícios de uma só vez:

Documentação sempre precisa
Cobertura de teste gratuita para seus exemplos públicos

Se um exemplo deixar de funcionar, o conjunto de testes falhará.

Nome do pacote nos exemplos

Os testes de documentação são executados como se viessem de fora do pacote, portanto faça referência aos itens pelo nome do pacote (por exemplo, my_crate::func) ou por uma importação use.

Blocos delimitados e indentados

Os testes de documentação aceitam dois estilos de bloco:

Um bloco delimitado por três crases, que permite anotações como no_run
Um bloco indentado (quatro espaços), como nos exemplos mostrados aqui

Blocos delimitados são mais comuns em código real.

Verificação rápida

O que faz uma linha que começa com # dentro de um bloco de código de teste de documentação?

Recapitulação

Você aprendeu sobre testes de documentação:

O código em blocos /// é compilado e executado por cargo test
Use asserções para verificar o comportamento
# oculta linhas de configuração na documentação renderizada
Anotações: no_run, ignore, should_panic, compile_fail
Elas mantêm os exemplos corretos automaticamente

Perguntas Frequentes

A aula “Testes de documentação” é grátis?

Sim — o texto completo de “Testes de documentação” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Learn Rust Coding, atualize para CoddyKit PRO. O curso de Learn Rust Coding inclui 4 aulas no total.

O que vou aprender em “Testes de documentação”?

Exemplos testados Você pratica Learn Rust Coding com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Learn Rust Coding?

Nenhuma experiência prévia é necessária. Learn Rust Coding no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Testes de documentação”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Learn Rust Coding?

Sim. Cada aula de Learn Rust Coding inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Learn Rust Coding