Lints de Documentação

Lints de documentação garantem que itens da API pública tenham comentários rustdoc e links de documentação válidos. Habilite missing_docs para bibliotecas das quais os consumidores dependem.

Receita

[lints.rust]
missing_docs = "warn"
broken_intra_doc_links = "deny"

/// Retorna o ID do usuário.
///
/// # Erros
///
/// Falha quando o ID não é encontrado.
pub fn user_id() -> Result<u64, Error> { todo!() }

Quando usar isso: Crates publicados, bibliotecas de plataforma internas e qualquer superfície de API pub.

Exemplo de Trabalho

[lints.rust]
missing_docs = "warn"
unsafe_code = "forbid"

//! Documentação em nível de crate para `orders`.
//!
//! # Exemplos
//!
//! ```
//! use orders::Client;
//! ```
 
/// Cliente HTTP para a API de pedidos.
pub struct Client;

cargo doc --no-deps --document-private-items
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

O que isso demonstra:

//! documenta o crate/módulo
/// documenta o item seguinte
Seções # Errors, # Panics, # Safety esperadas pelas diretrizes da API
RUSTDOCFLAGS="-D warnings" falha em links quebrados no CI

Análise Profunda

Lints de Documentação Chave

Lint	Captura
`missing_docs`	Itens `pub` indocumentados
`broken_intra_doc_links`	Links `[WrongType]`
`missing_crate_level_docs`	Documentação raiz de crate vazia
`invalid_html`	Tags inválidas na documentação

Seções do rustdoc

Exemplos - doctest ou no_run
Erros - variantes de Result
Segurança - obrigatório para pub unsafe fn

Armadilhas

Documentando cada fn privada - ruído. Correção: missing_docs tem como alvo pub por política padrão; permite módulos privados.
Links quebrados após renomear - a documentação do CI falha. Correção: RUSTDOCFLAGS="-D warnings" em PRs.
Comentários de documentação vazios - satisfazem o lint sem valor. Correção: revisar para um propósito de uma linha + erros.
unsafe sem seção de Segurança - aviso do rustdoc. Correção: modelo obrigatório para API unsafe.
Exemplos que não compilam - doctests falham. Correção: cargo test --doc no CI.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`warn` vs `deny` missing_docs	Adoção gradual	Crate público Greenfield
Apenas `mdbook` externo	Guias narrativos	Substituindo referência de API
`#[doc(hidden)]`	Reexportações internas	Ocultando erros da API pública

FAQs

missing_docs em binários?

Frequentemente relaxado; foco em crates de biblioteca no workspace.

Como documentar erros?

Liste o comportamento de cada variante de Error em # Errors com quando ocorre.

Doctest em cada `pub fn`?

Não é obrigatório; pelo menos um exemplo de crate e doctests em APIs complexas.

Como corrigir links intra-doc?

Use o caminho completo [Client](Client) no mesmo módulo ou caminhos [super::foo] que o rustdoc resolve.

docs.rs vs lints de documentação local?

Mesmo rustdoc; o cargo doc do CI detecta problemas antes de publicar.

Documentar enums?

Documente o enum e cada variante se for público, especialmente enums de erro.

E sobre reexportações?

#[doc(inline)] em pub use mostra a documentação no local da reexportação.

missing_docs em testes?

Geralmente N/A para módulos de teste; helpers públicos em crates de integração devem ser documentados ou mantidos privados.

Como impor em um workspace?

[lints.rust] missing_docs = "warn" compartilhado em cada Cargo.toml de lib ou padrão de herança de lint do workspace.

Documentar traits `unsafe`?

# Safety no trait e implementações explicando os invariantes que os mantenedores devem cumprir.

Relacionados

Doctests - exemplos executáveis
Níveis e Atributos de Lint - níveis de lint
Diretrizes de API Rust - convenções de documentação
Convenções de Documentação - estilo da equipe

Versões da Pilha: 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+.

Lints de Documentação

Lints de documentação garantem que itens da API pública tenham comentários rustdoc e links de documentação válidos. Habilite missing_docs para bibliotecas das quais os consumidores dependem.

Receita

[lints.rust]
missing_docs = "warn"
broken_intra_doc_links = "deny"

/// Retorna o ID do usuário.
///
/// # Erros
///
/// Falha quando o ID não é encontrado.
pub fn user_id() -> Result<u64, Error> { todo!() }

Quando usar isso: Crates publicados, bibliotecas de plataforma internas e qualquer superfície de API pub.

Exemplo de Trabalho

[lints.rust]
missing_docs = "warn"
unsafe_code = "forbid"

//! Documentação em nível de crate para `orders`.
//!
//! # Exemplos
//!
//! ```
//! use orders::Client;
//! ```
 
/// Cliente HTTP para a API de pedidos.
pub struct Client;

cargo doc --no-deps --document-private-items
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

O que isso demonstra:

//! documenta o crate/módulo
/// documenta o item seguinte
Seções # Errors, # Panics, # Safety esperadas pelas diretrizes da API
RUSTDOCFLAGS="-D warnings" falha em links quebrados no CI

Análise Profunda

Lints de Documentação Chave

Lint	Captura
`missing_docs`	Itens `pub` indocumentados
`broken_intra_doc_links`	Links `[WrongType]`
`missing_crate_level_docs`	Documentação raiz de crate vazia
`invalid_html`	Tags inválidas na documentação

Seções do rustdoc

Exemplos - doctest ou no_run
Erros - variantes de Result
Segurança - obrigatório para pub unsafe fn

Armadilhas

Documentando cada fn privada - ruído. Correção: missing_docs tem como alvo pub por política padrão; permite módulos privados.
Links quebrados após renomear - a documentação do CI falha. Correção: RUSTDOCFLAGS="-D warnings" em PRs.
Comentários de documentação vazios - satisfazem o lint sem valor. Correção: revisar para um propósito de uma linha + erros.
unsafe sem seção de Segurança - aviso do rustdoc. Correção: modelo obrigatório para API unsafe.
Exemplos que não compilam - doctests falham. Correção: cargo test --doc no CI.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
`warn` vs `deny` missing_docs	Adoção gradual	Crate público Greenfield
Apenas `mdbook` externo	Guias narrativos	Substituindo referência de API
`#[doc(hidden)]`	Reexportações internas	Ocultando erros da API pública

FAQs

missing_docs em binários?

Frequentemente relaxado; foco em crates de biblioteca no workspace.

Como documentar erros?

Liste o comportamento de cada variante de Error em # Errors com quando ocorre.

Doctest em cada `pub fn`?

Não é obrigatório; pelo menos um exemplo de crate e doctests em APIs complexas.

Como corrigir links intra-doc?

Use o caminho completo [Client](Client) no mesmo módulo ou caminhos [super::foo] que o rustdoc resolve.

docs.rs vs lints de documentação local?

Mesmo rustdoc; o cargo doc do CI detecta problemas antes de publicar.

Documentar enums?

Documente o enum e cada variante se for público, especialmente enums de erro.

E sobre reexportações?

#[doc(inline)] em pub use mostra a documentação no local da reexportação.

missing_docs em testes?

Geralmente N/A para módulos de teste; helpers públicos em crates de integração devem ser documentados ou mantidos privados.

Como impor em um workspace?

[lints.rust] missing_docs = "warn" compartilhado em cada Cargo.toml de lib ou padrão de herança de lint do workspace.

Documentar traits `unsafe`?

# Safety no trait e implementações explicando os invariantes que os mantenedores devem cumprir.

Relacionados

Doctests - exemplos executáveis
Níveis e Atributos de Lint - níveis de lint
Diretrizes de API Rust - convenções de documentação
Convenções de Documentação - estilo da equipe

Versões da Pilha: 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+.

Lints de Documentação

Buscar na documentação

Lints de Documentação