Rustdoc

Todos los elementos del lenguaje de Rust se pueden documentar con la sintaxis especial ///.

/// Determine whether the first argument is divisible by the second argument.
///
/// If the second argument is zero, the result is false.
fn is_divisible_by(lhs: u32, rhs: u32) -> bool {
    if rhs == 0 {
        return false;  // Corner case, early return
    }
    lhs % rhs == 0     // The last expression in a block is the return value
}

El contenido se trata como Markdown. Todos los crates de la biblioteca de Rust publicados se documentan automáticamente en docs.rs mediante la herramienta rustdoc. Es propio documentar todos los elementos públicos de una API usando este patrón.

  • Muestra a los alumnos los documentos generados para el crate rand en docs.rs/rand.

  • Este curso no incluye diapositivas sobre rustdoc para ahorrar espacio, pero deben aparecer en el código real.

  • Los comentarios internos de los documentos se tratarán más adelante (en la página de módulos), no es necesario tratarlos aquí.

  • Los comentarios de rustdoc pueden contener fragmentos de código que podemos ejecutar y probar utilizando cargo test. Hablaremos de esto en la sección de pruebas.