Los comentarios y la documentación son texto escrito junto al código para explicar intención, uso y contexto.
En muchos lenguajes, la documentación es una herramienta externa (Doxygen, Javadoc, Sphinx…). En Rust, la documentación es parte del núcleo del lenguaje.
El compilador y Cargo vienen preparados de serie para convertir tus comentarios en una página web navegable, con búsqueda y ejemplos ejecutables.
Hoy vamos a ver los dos tipos de comentarios que existen en Rust y cómo generar esa documentación profesional con un solo comando.
Comentarios simples (//)
Son los comentarios de toda la vida. El compilador los ignora por completo. Sirven para explicar partes complejas de la lógica interna a alguien que está leyendo el código fuente.
fn main() {
// Esto es un comentario de una línea
let x = 5;
/*
Esto es un comentario de bloque.
Es menos común en Rust, la gente suele preferir
varias líneas de //
*/
let y = 10;
}Buena práctica: No comentes el “qué” (el código ya dice lo que hace), comenta el “por qué”.
- ❌
let x = x + 1; // Suma 1 a x(Obvio, ruido). - ✅
let x = x + 1; // Necesario para compensar el offset del sensor(Útil).
Comentarios de documentación (///)
Si usas tres barras /// en lugar de dos, estás creando un comentario de documentación. Estos comentarios sí son procesados por las herramientas de Rust.
Soportan formato Markdown (negritas, listas, enlaces, bloques de código) y se utilizan para generar la documentación HTML de tu API.
Se colocan justo antes del elemento que documentan (una función, un struct, un enum…).
/// Suma uno al número dado.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = hola_mundo::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
x + 1
}Secciones comunes
Aunque puedes escribir lo que quieras, la comunidad de Rust sigue unas convenciones estándar usando encabezados Markdown (#):
- # Examples: Muestra cómo se usa la función.
- # Panics: Explica en qué casos esta función podría hacer que el programa aborte (por ejemplo, si pasas un índice fuera de rango).
- # Errors: Si la función devuelve un
Result, explica qué condiciones provocan un error. - # Safety: Si la función es
unsafe, explica qué precauciones debe tomar el desarrollador.
Comentarios de nivel de módulo (//!)
A veces quieres documentar el archivo completo o el módulo, no un elemento específico. Para eso, usamos //! (con un signo de exclamación).
Estos comentarios documentan el elemento que los contiene (normalmente el fichero crate o mod), en lugar del elemento que les sigue. Se suelen poner al principio del archivo main.rs o lib.rs.
//! # Mi Librería Matemática
//!
//! `mi_libreria` es una colección de utilidades para realizar
//! cálculos complejos de forma muy ineficiente.
/// Suma dos números...
fn suma(...)Generando la documentación: cargo doc
Ahora que hemos decorado nuestro código con /// y Markdown, ¿cómo lo vemos? Abre tu terminal y ejecuta:
cargo doc --openEste comando:
Analiza tu código y extrae los comentarios /// y //!.
Genera un sitio web estático (HTML, CSS, JS) en la carpeta target/doc.
La bandera --open abre automáticamente tu navegador predeterminado mostrando la web.
Verás una web, con barra de búsqueda, barra lateral de navegación y todo el estilo visual de la documentación oficial de Rust. ¡Y no has tenido que configurar nada!
cargo doc no solo documenta TU código. También genera la documentación de todas las dependencias (librerías) que use tu proyecto. Esto es increíblemente útil para consultar cómo funciona una librería externa sin tener que buscarla en Google; tienes la documentación de la versión exacta que usas, offline y localmente.
Pruebas de documentación (doc tests)
¿Te ha pasado alguna vez que copias un ejemplo de la documentación de una librería, lo pegas en tu código y no funciona porque la documentación estaba desactualizada?
En Rust, los bloques de código Rust dentro de los comentarios /// pueden ejecutarse como pruebas.
Cuando ejecutas cargo test, Rust no solo corre tus tests unitarios, también extrae los bloques de código de tu documentación y los ejecuta. Si tu ejemplo no compila o falla, cargo test fallará.
/// Divide dos números.
///
/// # Examples
///
/// ```
/// let resultado = hola_mundo::dividir(10, 2);
/// assert_eq!(resultado, 5);
/// ```
///
/// ```should_panic
/// // Este ejemplo documenta que dividir por cero causa pánico
/// hola_mundo::dividir(10, 0);
/// ```
pub fn dividir(a: i32, b: i32) -> i32 {
if b == 0 { panic!("No se puede dividir por cero"); }
a / b
}Esto ayuda a que los ejemplos sigan estando actualizados. Si cambias la función pero olvidas adaptar el ejemplo, las pruebas de documentación te avisarán.
