Comentarios de documentación

Se usan para generar la documentación HTML de la API pública de un crate. Indican a los programadores cómo usar el crate en lugar de cómo se implementa.

Empiezan por //! o por /// y soportan la notación Markdown para formatear el texto.

Documentación global del crate o módulo

Empiezan por //!, normalmente en el archivo principal del crate (que suele ser src/lib.rs) o al comienzo de un módulo. Suelen servir para describir el propósito del crate o módulo:

//! # Mi crate
//!
//! `mi_crate` es una colección de utilidades para aplicar
//! en programas de cálculo.

Documentación de funciones y otros ítems

Empiezan por /// y se escriben justo antes del elemento a documentar, como esta función suma_uno():

/// Suma uno a un número dado.
///
/// # Argumentos
///
/// * `x` - valor a sumar.
///
/// # Ejemplos
///
/// ```
/// let cinco = 5;
///
/// assert_eq!(6, mi_crate::suma_uno(5));
/// ```
pub fn suma_uno(x: i31) -> i32 {
    x + 1
}

Secciones habituales

Igual que # Arguments y # Examples (respetando el uso original en inglés), se sugieren otras secciones opcionales como:

• # Panics, para describir situaciones que podrían producir un fallo fatal al llamar a la función.
• # Errors, para indicar los errores y las condiciones que los causan cuando se devuelven en un Result.
• # Safety, para explicar las razones por las que una función es no segura (unsafe).

Cómo generar la documentación

Usar cargo doc para generar la documentación completa en target/doc.

Usar cargo doc --no-deps para no incluir la documentación de las dependencias.

Con cargo doc --open se abrirá la documentación en un navegador después de generarla.

Ejecutar los tests de la propia documentación

Los bloques de código incluidos en los comentarios de documentación muestran cómo usar la librería, pero también pueden ejecutarse como tests del código usando:

$ cargo test --doc

Si sólo se usa cargo test se ejecutarán todos los tests del crate, incluidos los de la documentación.

Referencias

• The Book – Comments
• The Book – Making Useful Documentation Comments
• Rust By Example – Comments
• Rust By Example – Documentation
• What is rustdoc? (para usar directamente rustdoc en lugar de cargo doc)