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
emdocs.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.