rustdoc es la herramienta que genera documentación HTML a partir de comentarios del código Rust.
Rust incluye esta herramienta de serie. Cuando instalas Rust, ya tienes todo lo necesario para generar una página web preciosa (HTML/CSS) con la documentación de tu proyecto. Es la misma herramienta que usa la documentación oficial de la librería estándar.
| Símbolo | Uso | ¿Dónde va? | ¿Sale en la web? |
|---|---|---|---|
// | Notas internas para programadores | Cualquier sitio | No |
/// | Documentación de un elemento | Justo antes de la función/struct | Sí |
//! | Documentación del contenedor (módulo/crate) | Al principio del archivo | Sí |
Comentarios de documentación (///)
Hasta ahora hemos usado // para comentarios normales. Estos son para ti o para otros desarrolladores que lean el código fuente.
Para documentar la API pública (para los usuarios de tu librería), usamos tres barras: ///.
Estos comentarios soportan Markdown completo.
/// Suma uno al número dado.
///
/// # Examples
///
/// ```
/// let x = 5;
/// let y = mi_crate::sumar_uno(x);
///
/// assert_eq!(y, 6);
/// ```
pub fn sumar_uno(x: i32) -> i32 {
x + 1
}Pruebas de documentación
Fíjate en el bloque de código dentro del comentario de arriba. Parece un simple ejemplo de Markdown, ¿verdad?
En un comentario de documentación, ese bloque Rust puede convertirse en una prueba.
Cuando ejecutas cargo test, Rust no solo corre los tests unitarios (src) y los de integración (tests/). También procesa los bloques de código Rust de la documentación. Podemos modificar su comportamiento con atributos como no_run, compile_fail o ignore.
- Si el ejemplo compila y corre bien: ✅ El test pasa.
- Si cambias la función
sumar_unopero olvidas actualizar el ejemplo: 💥 El test falla.
Esto ayuda a que los ejemplos sigan compilando y mantengan el comportamiento esperado. El texto explicativo todavía puede quedarse desactualizado, así que también necesita revisión.
Secciones habituales
Aunque puedes escribir lo que quieras en Markdown, la comunidad de Rust usa varias convenciones para organizar la información con encabezados (#).
# Examples
Muestra cómo se usa la función. Cuando el bloque participa en los doctests, Cargo puede comprobarlo automáticamente.
# Panics
Si tu función puede entrar en pánico (por ejemplo, unwrap o división por cero), debes documentarlo aquí. El usuario necesita saber qué inputs evitar.
/// Divide dos números.
///
/// # Panics
///
/// Entrará en pánico si `b` es 0.
pub fn dividir(a: i32, b: i32) -> i32 {
if b == 0 { panic!("División por cero"); }
a / b
}# Errors
Si tu función devuelve Result, explica en qué circunstancias devolverá Err y qué tipo de error será.
# Safety
Si tu función es unsafe (insegura), debes explicar qué condiciones tiene que garantizar el usuario para llamarla sin romper la memoria.
Documentar el módulo (//!)
A veces quieres documentar el archivo entero (el módulo o la crate), no un item específico. Para eso, usamos el comentario con signo de exclamación: //!.
Suele ponerse en la primera línea de src/lib.rs o src/main.rs.
//! # Mi Librería de Matemáticas
//!
//! `mi_lib` es una colección de utilidades para hacer
//! aritmética compleja de forma sencilla.
//!
//! ## Uso básico
//! ...
// Aquí empieza el código normal
pub mod algebra;Generando el sitio web
Para ver el resultado final, simplemente ejecuta:
$ cargo doc --openEste comando:
- Analiza tu código y tus comentarios.
- Genera una web estática en
target/doc. - Abre tu navegador predeterminado mostrando la documentación.
¡Y no solo documenta tu código! También genera la documentación de todas tus dependencias.
Es decir, si usas serde o tokio, tendrás su documentación disponible offline y enlazada con la tuya en el mismo formato.
