Convenções de Documentação
As convenções de documentação mantêm o conhecimento de Rust onde os engenheiros trabalham: /// rustdoc para APIs, docs/adr/ para decisões, runbooks para plantão e arquivos README com propriedade - não wikis espalhadas que se desviam do main.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
service-repo/
README.md # quickstart, proprietários, links
docs/
adr/
runbooks/
specs/
crates/*/src/lib.rs # docs//! no nível do móduloQuando usar isso:
- Inicialização de novo serviço
- Auditoria encontra runbooks ausentes
- Preparação para lançamento de código aberto
- Reclamações de integração "não consigo encontrar como implantar"
Exemplo de Trabalho
//! Lógica de domínio de pedidos - cálculos de dinheiro em centavos inteiros.
//!
//! # Exemplos
//! ```
//! use orders_domain::total_cents;
//! assert_eq!(total_cents(100, 20).unwrap(), 120);
//! ```
pub fn total_cents(subtotal: i64, tax: i64) -> Result<i64, &'static str> {
if subtotal < 0 || tax < 0 {
return Err("valor negativo");
}
Ok(subtotal + tax)
}# docs/runbooks/pool-exhaustion.md
Veja a lição LL-0042. Passos: verificar p95 de aquisição, verificar DATABASE_MAX_CONNECTIONS, reverter se a implantação estiver correlacionada.Mergulho Profundo
Tipos de Documentação
| Tipo | Localização | Público |
|---|---|---|
| rustdoc | src/ | Consumidores do Crate |
| ADR | docs/adr/ | Futuros mantenedores |
| Runbook | docs/runbooks/ | Plantão |
| Especificação Técnica | docs/specs/ | PM + entrega de engenharia |
| Site de SME | site/rust/ | Aprendizado da frota |
Barra de Qualidade
- Exemplos compilam (
cargo test --doc). - Status do ADR atualizado (Proposto/Aceito/Substituído).
- Data
last_verifieddo Runbook dentro de 90 dias. - README atualizado sobre mudança de propriedade no mesmo PR.
Sincronização com o Site de SME
Artigos internos resumem padrões; a documentação do repositório é a fonte da verdade para comandos e SHAs específicos do serviço.
Armadilhas
- Runbooks apenas em Wiki - Obsoletos após refatoração. Correção: Runbooks no repositório; apenas links na wiki.
- Documentação
//!de módulo vazia - Correção: Necessário para crates públicos na verificação de CI. - ADR não vinculado do README - Correção: Seção "Arquitetura" com os últimos 5 ADRs.
- Copiar e colar
kubectlda produção - Correção: Parametrizar o ambiente em modelos de runbook.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| mdBook para livro de crate | Grande OSS público | Pequena biblioteca interna |
| Notion para especificações | Colaboração de PM | Armazenamento único de implantação/runbook |
| auto-doc de OpenAPI | Superfície HTTP | Ensino de lógica de domínio |
FAQs
Documentar itens privados?
Documentação pub(crate) para módulos complexos; não é obrigatório em todas as funções.
ADR vs Arquivo RFC?
A pasta RFC contém propostas; aceitas se tornam ADR.
Documentação não em inglês?
Inglês é o padrão para a frota; o produto pode localizar apenas o que é voltado para o usuário.
Documentação gerada em CI?
Publica rustdoc no portal interno em tags de lançamento.
Comentar o porquê, não o quê?
O porquê, não o quê; vincular ADR para trade-offs não óbvios.
Relacionados
- Registros de Decisão de Arquitetura - processo de ADR
- Diretrizes de Contribuição - como atualizar a documentação
- Padrões de Codificação - exemplos de documentação
- Playbooks de Resposta a Incidentes - conteúdo de runbook
- Melhores Práticas de Governança - resumo
Versões de Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.