Learn Rust Coding · Aula

Comentários de documentação

Documentação com ///

Comentários de documentação é uma aula grátis de Learn Rust Coding no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Learn Rust Coding, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Learn Rust Coding inclui 4 aulas no total.

Documentação em Rust

Rust oferece documentação integrada à linguagem desde o início. Comentários especiais se tornam documentação HTML gerada por cargo doc.

Comentários externos de documentação

Use /// para documentar o item que vem depois dele — funções, estruturas, enumerações e outros. O texto aceita Markdown.

/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Formatação com Markdown

Os comentários de documentação são renderizados como Markdown: títulos, listas, negrito e links funcionam. O código em linha usa crases, e os títulos de seção começam com #.

/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
    width * height
}

Seções comuns da documentação

Títulos convencionais tornam a documentação fácil de consultar:

# Examples — exemplos de uso
# Panics — situações em que ocorre um pânico
# Errors — erros que a função retorna
# Safety — invariantes do código não seguro

Comentários internos de documentação

Use //! para documentar o item que o contém, normalmente um módulo ou o pacote inteiro. Coloque-o no início do arquivo.

//! # My Math Crate
//!
//! Utilities for basic arithmetic.

pub fn double(n: i32) -> i32 {
    n * 2
}

Documentando estruturas e campos

Cada item público, incluindo campos de estruturas, pode ter seu próprio comentário de documentação.

/// A point in 2D space.
pub struct Point {
    /// The horizontal coordinate.
    pub x: f64,
    /// The vertical coordinate.
    pub y: f64,
}

Gerando documentação

cargo doc cria a documentação HTML em target/doc. Adicione --open para visualizá-la no navegador.

cargo doc --open

Excluindo dependências

Por padrão, o Cargo também documenta suas dependências. Use --no-deps para criar a documentação apenas do seu pacote.

cargo doc --no-deps --open

Links dentro da documentação

Crie um link para outros itens escrevendo o caminho deles entre colchetes. Rust resolve o caminho e cria um link clicável na documentação gerada.

/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

Por que documentar?

Uma boa documentação traz benefícios:

É gerada automaticamente em HTML pesquisável
É publicada gratuitamente em docs.rs quando você publica um pacote
Os exemplos na documentação são testados (testes de documentação)
Ajuda sua equipe e você no futuro

Documentando um módulo

Combine comentários internos e externos: um arquivo de módulo começa com //!, descrevendo o módulo, e cada item interno usa ///.

//! Geometry helpers.

/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
    side * 4.0
}

Verificação rápida

Qual sintaxe de comentário documenta o item que vem logo depois?

Recapitulação

Você aprendeu sobre comentários de documentação:

/// documenta o item seguinte; //! documenta o item que o contém
Eles aceitam Markdown e seções como # Examples
Os links dentro da documentação conectam itens
cargo doc --open gera e exibe a documentação HTML

Perguntas Frequentes

A aula “Comentários de documentação” é grátis?

Sim — o texto completo de “Comentários de documentação” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Learn Rust Coding, atualize para CoddyKit PRO. O curso de Learn Rust Coding inclui 4 aulas no total.

O que vou aprender em “Comentários de documentação”?

Documentação com /// Você pratica Learn Rust Coding com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Learn Rust Coding?

Nenhuma experiência prévia é necessária. Learn Rust Coding no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Comentários de documentação”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Learn Rust Coding?

Sim. Cada aula de Learn Rust Coding inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Learn Rust Coding