La documentación es una parte integral del ecosistema Rust. En lugar de usar comentarios simples para explicar qué hace una función, Rust utiliza rustdoc, una herramienta que transforma comentarios especiales en páginas HTML profesionales, navegables y altamente estructuradas.

Existen dos tipos fundamentales de comentarios de documentación:
1. Comentarios de módulo (//!): Se colocan al principio de un archivo para documentar el módulo o el crate completo. Se usan para dar una visión general de la funcionalidad de la librería.
2. Comentarios de ítems (///): Se colocan justo encima de un elemento (como una struct, enum o fn) para documentar ese elemento específico.

Una de las características más potentes de Rust es el Doc Test. Si escribes un bloque de código dentro de un comentario /// usando triple comilla invertida (``),cargo test` ejecutará ese código. Esto garantiza que tus ejemplos de documentación no queden obsoletos cuando cambies el código, ya que si el ejemplo falla, la compilación de las pruebas fallará.

Para generar la documentación y verla en tu navegador, simplemente utiliza el comando cargo doc --open.

Para mantener la documentación organizada, se utilizan secciones con encabezados Markdown, como # Examples para mostrar código, # Panics para advertir sobre casos donde la función detenga el programa, o # Errors para indicar cuándo una función devuelve un Result::Err.

//! Este módulo proporciona herramientas básicas para manejar números.
//! Se usa `//!` para documentar la funcionalidad general de este módulo.

/// Una estructura que representa un valor numérico con metadatos.
pub struct Valor {
    /// El valor entero almacenado.
    numero: i32,
}

impl Valor {
    /// Crea una nueva instancia de `Valor` con un número dado.
    ///
    /// # Examples
    ///
    /// Un ejemplo de cómo crear un `Valor`:
    ///
    ///

/// // Este bloque se ejecutará automáticamente en cargo test
/// let v = Valor::nuevo(42);
/// assert_eq!(v.obtener_valor(), 42);
/// 

    pub fn nuevo(numero: i32) -> Self {
        Valor { numero }
    }

    /// Devuelve el valor entero contenido en la estructura.
    ///
    /// # Panics
    ///
    /// Esta función no entra en pánico, pero sirve para ilustrar 
    /// cómo se documentarían secciones de error o pánico.
    pub fn obtener_valor(&self) -> i32 {
        self.numero
    }
}

fn main() {
    let mi_valor = Valor::nuevo(100);
    println!("El valor es: {}", mi_valor.obtener_valor());
}

Explicación del Código

  • //! (Línea 1): Documenta el módulo completo. Al generar la documentación, este texto aparecerá en la página principal del módulo.
  • /// Una estructura... (Línea 4): Documenta la estructura Valor. Gracias a que es pub (pública), aparecerá en la documentación generada para otros usuarios.
  • /// El valor entero... (Línea 6): Documenta el campo numero dentro de la estructura Valor.
  • /// Crea una nueva instancia... (Línea 13): Documenta el método nuevo. Incluye una sección # Examples que contiene un bloque de código Markdown.
  • El bloque de código en nuevo: Este bloque es un doc test. Rust extraerá este código y lo probará durante cargo test para asegurar que Valor::nuevo(42) realmente funciona como se describe.
  • pub fn nuevo (Línea 23): Es el constructor de la estructura Valor.
  • /// Devuelve el valor... (Línea 32): Documenta la función obtener_valor e incluye una sección # Panics para cumplir con las convenciones de documentación de Rust.
  • pub fn obtener_valor (Línea 38): El método que retorna el tipo i32 almacenado en el campo numero.

N° 9