Documentação em Rust: técnicas e ferramentas avançadas

Introdução: Por que a documentação em Rust é mais do que comentários

O ecossistema Rust é conhecido por seu rigor e confiabilidade. No entanto, mesmo o código mais elegante é inútil sem documentação de qualidade. No nível inicial, basta escrever algumas linhas /// para funções públicas. Mas quando seu projeto cresce para vários crates com dezenas de módulos, surge a questão das técnicas avançadas de documentação.

Neste artigo, exploraremos ferramentas e técnicas que ajudarão você a criar documentação de nível empresarial: desde testes automáticos de exemplos até geração de livros e integração com CI/CD.

1. Doctests: documentação que não mente

A principal "sacada" do rustdoc é a capacidade de incorporar exemplos de código executáveis diretamente nos comentários. Esses exemplos são automaticamente compilados e executados ao rodar cargo test. Isso garante que sua documentação esteja sempre atualizada.

Doctest básico

/// Retorna a soma de dois números.\n///\n/// # Exemplo\n///\n/// ```\n/// let result = my_crate::add(2, 3);\n/// assert_eq!(result, 5);\n/// ```\npub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}

Técnicas avançadas com doctest

Você pode ocultar linhas de preparação que não devem aparecer na documentação usando # :

/// # Exemplo com inicialização\n///\n/// ```\n/// # use std::collections::HashMap;\n/// let mut map = HashMap::new();\n/// map.insert("key", 42);\n/// assert_eq!(map.get("key"), Some(&42));\n/// ```

Também é possível verificar se o código não compila (por exemplo, demonstrando erros de tempo de compilação):

/// ```compile_fail\n/// let x: i32 = "string"; // Erro: incompatibilidade de tipos\n/// ```

2. Atributos de documentação: controle e metadados

Os atributos #[doc(...)] permitem ajustar finamente a exibição da documentação.

Ocultando elementos

/// Função interna, não destinada ao uso público.\n#[doc(hidden)]\npub fn internal_helper() {}

Categorização e pesquisa

/// Grupo de utilitários para trabalhar com rede.\n#[doc(alias = "net")]\n#[doc(alias = "socket")]\npub mod network {\n    // ...\n}

Incorporando documentação de outro local

/// Veja a [documentação do módulo](index.html) para informações gerais.\n#[doc(include = "docs/faq.md")]\npub fn complex_function() {}

3. Cross-references e navegação

O Rustdoc suporta links para outros elementos da documentação. Isso cria uma estrutura coesa e fácil de ler.

Links para funções e tipos

/// Use [`Config::new`] para criar uma instância.\n///\n/// Para configuração mais complexa, consulte o módulo [`config`].\npub struct Config { /* ... */ }

Links para crates externos

/// Esta função usa [serde_json] para serialização.\n///\n/// [serde_json]: https://docs.rs/serde_json\npub fn to_json() {}

4. Ferramentas para grandes projetos: mdBook e documentação de crate

Quando apenas cargo doc não é suficiente, o mdBook vem em socorro — uma ferramenta para criar livros a partir de arquivos Markdown. É ideal para escrever guias, tutoriais e documentação de arquitetura.

Início rápido com mdBook

# Instalação\ncargo install mdbook\n\n# Criando um projeto\nmdbook init my-book\ncd my-book\nmdbook serve --open

Integração com rustdoc

Você pode incorporar documentação do mdBook no cargo doc usando o atributo #[doc = include_str!()]:

/// # Arquitetura\n///\n/// Descrição detalhada da arquitetura da biblioteca:\n///\n#[doc = include_str!("../docs/architecture.md")]\npub mod core {\n    // ...\n}

Conclusão