cargo doc

Se puede haber observado que la documentación de Rust siempre es parecida. En el lado izquierdo aparecen los struct y trait y los ejemplos de código aparecen a la derecha. Esto se debe a que se puede generar de forma automática la documentación mediante el uso de cargo doc.

Incluso con un programa que no hace nada, se puede aprender sobre los rasgos en Rust. Por ejemplo, a continuación hay dos struct que no hacen casi nada y una función fn main() que casi tampoco hace nada:

struct DoesNothing {}
struct PrintThing {}

impl PrintThing {
    fn prints_something() {
        println!("I am printing something");
    }
}

fn main() {}

Pero si se teclea cargo doc --open, se puede observa que existe mucha información, más de la que puede que se esperara. Lo primero que muestra es:

Crate rust_book

Structs
DoesNothing
PrintThing

Functions
main

Pero si se teclea en una de las struct mostrará muchos rasgos que implementa sin haberse hecho por parte del desarrollador:

Struct rust_book::DoesNothing
[+] Show declaration
Auto Trait Implementations
impl RefUnwindSafe for DoesNothing
impl Send for DoesNothing
impl Sync for DoesNothing
impl Unpin for DoesNothing
impl UnwindSafe for DoesNothing
Blanket Implementations
impl<T> Any for T
where
    T: 'static + ?Sized,
[src]
[+]
impl<T> Borrow<T> for T
where
    T: ?Sized,
[src]
[+]
impl<T> BorrowMut<T> for T
where
    T: ?Sized,
[src]
[+]
impl<T> From<T> for T
[src]
[+]
impl<T, U> Into<U> for T
where
    U: From<T>,
[src]
[+]
impl<T, U> TryFrom<U> for T
where
    U: Into<T>,
[src]
[+]
impl<T, U> TryInto<U> for T
where
    U: TryFrom<T>,

Esto se debe a que Rust los implementa de forma automática para todos los tipos que se crean.

Si, además, se añade algo de comentarios de documentación \\\, aparecerán en cargo doc.

/// This is a struct that does nothing
struct DoesNothing {}
/// This struct only has one method.
struct PrintThing {}
/// It just prints the same message.
impl PrintThing {
    fn prints_something() {
        println!("I am printing something");
    }
}

fn main() {}

Que mostrará ahora:

Crate rust_book
Structs
DoesNothing This is a struct that does nothing
PrintThing  This struct only has one method.
Functions
main

cargo doc es muy útil cuando se usan librerías de otras personas. Porque normalmente estas librerías están en múltiples sitios web. Puede necesitarse tiempo para buscarlas todas. Con cargo doc se mostrará la documentación de todas ellas desde el propio ordenador personal.