Documentação em Rust: como escrever código que fala por si só

Por que a documentação em Rust não é uma obrigação chata, mas um superpoder

Imagine que você abre um crate de outra pessoa em Rust e lá está — vazio. Nenhum comentário, nenhuma linha de documentação. Apenas código puro com genéricos, traits e lifetimes. Familiar? Doloroso? É por isso que o tema da documentação em projetos Rust é mais urgente do que nunca.

Rust é famoso por sua segurança e desempenho, mas seu sistema de tipos pode ser complexo para iniciantes. Uma boa documentação transforma seu código de "hieróglifos" em um guia compreensível. Além disso, em Rust, a documentação não é apenas texto. São exemplos executáveis que garantem que seu código funciona como prometido.

Neste artigo, abordaremos as melhores práticas de documentação de código em Rust que ajudarão você a escrever projetos claros, sustentáveis e profissionais. Você aprenderá a usar o rustdoc, formatar corretamente comentários doc e criar documentação pela qual os usuários do seu código serão gratos.

Fundamentos: o que é documentação em Rust e por que ela é necessária

Em Rust, existem dois tipos de comentários: os comuns (// e /* */) e os comentários doc (/// e //!). Os comentários doc são automaticamente coletados pela ferramenta rustdoc e transformados em documentação HTML. Esta é uma ferramenta integrada que acompanha o compilador — você não precisa instalar nada adicional.

Por que perder tempo com documentação? Aqui estão três razões de ferro:

• Velocidade de desenvolvimento: você esquecerá seu código em um mês. A documentação é um lembrete para o seu eu futuro.
• Integração de novos desenvolvedores: uma boa documentação reduz o tempo de entrada no projeto de semanas para horas.
• Testes de presente: exemplos em comentários doc podem ser executados como testes. Isso é chamado de doctests.

Vamos ver um exemplo simples. Aqui está como se parece a documentação básica de uma função:

/// Calcula o fatorial do número n////// # Arguments////// * `n` - Número inteiro não negativo////// # Returns////// Retorna um `u64` - o fatorial do número n////// # Examples////// ```/// use my_crate::math::factorial;////// assert_eq!(factorial(5), 120);/// ```pub fn factorial(n: u64) -> u64 {    (1..=n).product()}

Execute cargo doc --open e você verá uma página HTML lindamente formatada com esta descrição. E se você executar cargo test, o exemplo dentro da documentação também será executado como um teste. Conveniente, não é?

Estrutura de um bom comentário doc: segredos dos profissionais

Escrever documentação é uma arte. Na comunidade Rust, existem padrões estabelecidos que tornam a documentação útil e uniforme. Vamos analisá-los em detalhes.

O primeiro parágrafo é o título

A primeira linha de um comentário doc deve ser uma descrição breve do que a função, estrutura ou módulo faz. O rustdoc a usa para criar uma lista resumida de todos os elementos. Pense nisso como o título de uma notícia — deve deixar claro imediatamente do que se trata.

/// Ordena um array usando o método da bolha (Bubble Sort).////// Uma descrição detalhada pode ser adicionada aqui...pub fn bubble_sort(arr: &mut [i32]) { ... }

Seções: use cabeçalhos Markdown

Rust suporta Markdown em comentários doc. Use seções padrão para estruturar as informações:

• # Examples — exemplos de uso
• # Panics — quando a função pode causar pânico
• # Errors — quais erros retorna (se retornar Result)
• # Safety — se a função for unsafe, explique por quê
• # Arguments — descrição dos parâmetros