`cargo doc` în Rust

Generează documentația HTML a proiectului din comentariile ///, cu toate tipurile și funcțiile publice, ca pe docs.rs.

Sintaxă

cargo doc                       # documentația proiectului și a dependențelor
cargo doc --open                # și o deschide în browser
cargo doc --no-deps             # doar proiectul tău
rustup doc --std                # documentația bibliotecii standard, offline

Ce face `cargo doc`

cargo doc rulează rustdoc și creează un site HTML în target/doc/: câte o pagină pentru fiecare modul, structură, enum, trait și funcție publică, cu textul din comentariile /// și //!, semnăturile, implementările de trait-uri și un motor de căutare. Este același format ca pe docs.rs, unde apare automat documentația oricărui crate publicat.

Implicit sunt documentate și toate dependențele, foarte util când lucrezi offline: ai documentația exactă a versiunilor pe care le folosești. --no-deps generează doar proiectul tău, iar --open deschide pagina în browser. --document-private-items include și elementele private.

Documentația bibliotecii standard este instalată de rustup (componenta rust-docs) și se deschide cu rustup doc --std.

Exemple

Exemplul 1: Generarea documentației

Pagina principală a bibliotecii calcule este target/doc/calcule/index.html. Funcția media apare cu textul din /// și cu exemplul ei.

$ cargo doc --no-deps
$ ls target/doc

Rezultat în terminal

 Documenting calcule v0.1.0 (/home/ana/proiecte/calcule)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.65s
   Generated /home/ana/proiecte/calcule/target/doc/calcule/index.html
calcule  crates.js  help.html  search.index  settings.html  src  src-files.js  static.files

Exemplul 2: Ce ajunge în documentație

Doar elementele publice apar implicit. //! devine descrierea crate-ului, iar fiecare /// descrierea elementului de sub el; titlurile Markdown (# Panics) devin secțiuni.

// src/lib.rs
//! Funcții pentru calculul mediilor școlare.

/// Media aritmetică a notelor.
///
/// # Panics
/// Dă panică dacă lista de note este goală.
pub fn media(note: &[f64]) -> f64 {
    assert!(!note.is_empty(), "lista de note este goală");
    suma(note) / note.len() as f64
}

// nu apare în documentație: nu este pub
fn suma(note: &[f64]) -> f64 {
    note.iter().sum()
}

Ce apare în target/doc/calcule/index.html

Crate calcule
Funcții pentru calculul mediilor școlare.

Functions
  media    Media aritmetică a notelor.

Greșeli frecvente

Cauți în documentație o funcție care nu apare: nu este pub. Folosește --document-private-items pentru documentația internă.
Pui link-uri spre alte elemente ca text simplu. Rustdoc transformă [`Vec`] sau [`media`] în link-uri automate spre pagina elementului.

Comenzi înrudite

comentarii și documentație (//, ///, //!): // și /* */ sunt comentarii obișnuite; /// și //! scriu documentație Markdown, transformată în HTML de cargo doc și testată de cargo test.
cargo publish: Împachetează biblioteca și o publică pe crates.io, de unde oricine o poate folosi cu cargo add. O versiune publicată nu mai poate fi ștearsă.
cargo test: Compilează proiectul în mod test și rulează toate testele: cele #[test], testele din tests/ și exemplele din documentație.
rustup: Instalează și actualizează Rust: compilatorul, Cargo și componentele lor, în mai multe versiuni (stable, beta, nightly) și pentru mai multe sisteme.

Ce face cargo doc