Lição 39: Documentação (Cargo Doc) — Manual Técnico do Mecha

1. Narrativa

Todo mecha que entra em combate precisa de um manual técnico completo. A engenharia de documentação é o processo de registrar cada sistema, cada função e cada comportamento para que futuros pilotos e engenheiros possam entender e manter a máquina. Em Rust, cargo doc transforma seus comentários em uma documentação HTML profissional.

2. Conceito

Rust trata documentação como parte do código. Principais recursos:

• /// — Comentários doc para o item seguinte (função, struct, enum)
• //! — Comentários doc para o item que o contém (módulo, crate)
• cargo doc — Gera documentação HTML
• cargo doc --open — Gera e abre no navegador
• Seções especiais: # Examples, # Panics, # Errors, # Safety
• Doc tests — Exemplos nos comentários são executados como testes

3. Requisitos

• Documentar funções com /// incluindo descrição e exemplos
• Documentar o módulo/crate com //!
• Usar seções especiais (# Examples, # Panics)
• Garantir que doc tests passem com cargo test

4. Design de Dados

graph LR
    A[Comentários ///] --> B[cargo doc]
    C[Comentários //!] --> B
    B --> D[Documentação HTML]
    A --> E[cargo test]
    E --> F[Doc Tests executam]

5. Diagrama de Fluxo

flowchart TD
    A[Escrever código com ///] --> B[cargo doc]
    B --> C[Gera HTML em target/doc/]
    C --> D[cargo doc --open]
    D --> E[Navegador exibe docs]
    A --> F[cargo test]
    F --> G[Doc tests são compilados]
    G --> H[Executa exemplos como testes]

6. Funções

Função	Descrição
nome_sensor_valido	Verifica nome com letras minúsculas e underscores
calibrar_sensor	Aplica fator e offset à leitura bruta
gerar_relatorio	Gera linhas formatadas dos sensores
filtrar_sensores	Filtra sensores por faixa de valor
media_sensores	Calcula média dos valores (panica com "média de sensores vazia" se vazio)
buscar_sensor	Busca sensor pelo nome
formatar_leitura	Formata valor com 2 casas decimais e unidade

7. Exemplo

/// Converte leitura bruta para unidades padrão
///
/// # Examples
///
/// ```
/// let resultado = calibrar_sensor(100.0, 1.5, -10.0);
/// assert_eq!(resultado, 140.0);
/// ```
pub fn calibrar_sensor(leitura: f64, fator: f64, offset: f64) -> f64 {
    leitura * fator + offset
}

8. Missão

1. Implementar nome_sensor_valido verificando formato do nome
2. Implementar calibrar_sensor aplicando fator e offset
3. Implementar gerar_relatorio formatando cada sensor como string
4. Implementar filtrar_sensores usando iteradores com faixa de valor
5. Implementar media_sensores somando e dividindo (panica com "média de sensores vazia" se vazio)
6. Implementar buscar_sensor procurando pelo nome
7. Implementar formatar_leitura com formatação de 2 casas decimais

9. Como Executar

cargo build
cargo test                    # roda testes + doc tests
cargo doc --open              # gera e abre documentação
cargo clippy -- -D warnings
cargo fmt --check

10. Dicas

• cargo test executa tanto testes normais quanto doc tests
• Doc tests falham se o exemplo não compilar ou a assertion falhar
• Use # para esconder linhas nos exemplos (setup code)
• cargo doc --no-deps gera docs apenas da sua crate, sem dependências
• Adicione /// # Safety para funções unsafe e /// # Errors para Result