Rustdoc

Todos os itens da linguagem podem ser documentados com a sintaxe especial ///.

/// Determine se o primeiro argumento é divisível pelo segundo argumento.
///
/// Se o segundo argumento for zero, o resultado é falso.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;  // Caso excepcional, retorne antes
    }
    lhs % rhs == 0     // A última expressão do bloco é o valor de retorno
}

O conteúdio é tratado como Markdown. Todos os crates publicados na biblioteca Rust são documentados automaticamente em docs.rs utilizando a ferramenta rustdoc. É idiomático documentar todos os itens públicos em uma API usando este padrão.

  • Mostre aos alunos os documentos gerados para o crate rand em docs.rs/rand.

  • Este curso não inclui o rustdoc nos slides, apenas para economizar espaço, mas em código real eles devem estar presentes.

  • Os comentários internos do documento são discutidos posteriormente (na página sobre módulos) e não precisam ser ser abordados aqui.

  • Os comentários do Rustdoc podem conter trechos de código-fonte, que podem ser executados e testados por meio de cargo test. Nós discutiremos estes testes na seção de Testes.