Doc tests: la documentación que se compila y no miente

En toda tu carrera has visto documentación que envejece hasta mentir: el ejemplo que ya no compila, la firma que cambió, el foo(x, y) que hoy pide tres argumentos. La documentación se pudre porque nada la ata a la verdad del código. Rust corta ese nudo con una idea tan simple como radical: los bloques de código que escribes dentro de los comentarios de documentación /// se compilan y se ejecutan como pruebas. Cuando lanzas cargo test, además de tus tests unitarios y de integración, rustdoc extrae cada ejemplo, lo envuelve en un programa, lo compila contra la versión actual de tu crate y lo corre. Si el ejemplo dejó de compilar, la suite falla. Si su assert_eq! ya no cuadra, la suite falla. La consecuencia es un tipo de documentación que la mayoría de lenguajes no puede ofrecer: una que no puede mentir, porque el compilador la vigila en cada commit.

El ejemplo que se ejecuta

Un comentario /// documenta el elemento que le sigue. Dentro, un bloque cercado con triple acento grave y etiqueta rust se convierte en un doc test:

/// Duplica un entero.
///
/// # Ejemplos
///
/// ```
/// use micrate::duplica;
///
/// assert_eq!(duplica(21), 42);
/// ```
pub fn duplica(x: i32) -> i32 {
    x * 2
}

El bloque no es decorativo: cargo test lo compila como un pequeño programa que importa tu crate, ejecuta las líneas y comprueba el assert_eq!. Si mañana renombras duplica o cambias su firma, este ejemplo dejará de compilar y la suite te lo gritará antes de que un usuario tropiece con él. La etiqueta por defecto de un bloque sin lenguaje es rust, así que puede omitirse; para prosa que no debe compilarse, se usa la etiqueta text.

Una comodidad clave: rustdoc envuelve tu ejemplo en una fn main implícita. Por eso el fragmento anterior no la escribe. Y como ese main puede tener el tipo de retorno adecuado, los doc tests soportan el operador ? si el bloque termina devolviendo Ok:

/// Parsea un puerto desde texto.
///
/// ```
/// let puerto: u16 = "8080".parse()?;
/// assert_eq!(puerto, 8080);
/// # Ok::<(), std::num::ParseIntError>(())
/// ```
pub fn documentacion() {}

Líneas ocultas: el ejemplo limpio por fuera, completo por dentro

Un ejemplo debe compilar de verdad, lo que a menudo exige líneas de andamiaje —imports, una construcción previa, el Ok(()) final— que distraen al lector sin enseñarle nada. Rust resuelve esta tensión con el prefijo #: una línea del bloque que empieza por # se compila y ejecuta, pero no se muestra en la documentación renderizada.

/// Suma los elementos de un vector.
///
/// ```
/// # use micrate::suma_total;
/// let datos = vec![1, 2, 3, 4];
/// assert_eq!(suma_total(&datos), 10);
/// ```
pub fn suma_total(v: &[i32]) -> i32 {
    v.iter().sum()
}

Quien lee la documentación ve solo las dos líneas centrales, nítidas y didácticas; el compilador, en cambio, ve también el use oculto y verifica el conjunto completo. Es la conciliación perfecta entre dos audiencias que suelen estar en conflicto: el humano que quiere claridad y la máquina que exige exactitud.

Hay un dividendo que trasciende la corrección: estos ejemplos son también la cara pública de tu crate. rustdoc los renderiza en la documentación que se publica en docs.rs, de modo que el mismo fragmento que el compilador verifica es el primero que un usuario lee al evaluar tu librería. Un ejemplo que compila da confianza; uno que además ilustra el caso de uso central vende la API mejor que cualquier párrafo. En Rust, la frontera entre probar, documentar y persuadir se desdibuja hasta casi desaparecer.

Atributos: gobernar qué se compila y qué se ejecuta

No todo ejemplo puede o debe ejecutarse. Un fragmento que abre una conexión de red compilaría, pero correrlo en CI sería frágil. Otro pretende ilustrar precisamente que algo no compila. Para eso, la valla del bloque acepta atributos tras la etiqueta:

• no_run — se compila (garantiza que la firma es válida) pero no se ejecuta. Ideal para ejemplos con efectos de red, ficheros o bucles infinitos.
• ignore — ni se compila ni se ejecuta. El último recurso; casi siempre no_run o text es una elección más honesta.
• should_panic — el ejemplo debe entrar en pánico para considerarse aprobado.
• compile_fail — el ejemplo debe fallar al compilar; si compilase, la prueba falla. Sirve para documentar que el sistema de tipos rechaza un mal uso.
• text — el bloque es prosa, no Rust; no se toca.

/// Este uso viola el borrow checker y no debe compilar:
///
/// ```compile_fail
/// let mut v = vec![1, 2, 3];
/// let primero = &v[0];
/// v.push(4);          // prestamo mutable con uno inmutable vivo
/// println!("{primero}");
/// ```
pub fn ejemplo_negativo() {}

Puedes ejecutar únicamente estas pruebas con cargo test --doc. El atributo compile_fail es especialmente elegante: convierte una garantía de seguridad —“el compilador rechaza esto”— en una prueba que se rompería si una futura versión, por descuido, empezara a aceptarlo.

flowchart TD
D[Escribes un ejemplo en un comentario tres barras] --> E[rustdoc lo extrae al ejecutar cargo test]
E --> W[Lo envuelve en un main implicito con soporte para interrogacion]
W --> A{Que atributo lleva la valla}
A -->|por defecto| R[Compila y ejecuta y verifica las aserciones]
A -->|no_run| C[Compila pero no ejecuta]
A -->|compile_fail| N[Debe fallar al compilar]
A -->|text| T[Prosa que no se toca]
style D fill:#cba6f7,color:#11111b
style W fill:#89b4fa,color:#11111b
style R fill:#a6e3a1,color:#11111b
style N fill:#f38ba8,color:#11111b