Documentar: rustdoc, /// y docs.rs

En la mayoría de los lenguajes documentar es un acto de fe y de disciplina: escribes prosa en algún formato, la generas con una herramienta que instalas aparte, la subes a un sitio que mantienes tú, y rezas para que no envejezca hasta mentir. Rust colapsa toda esa cadena en el propio flujo del lenguaje. Los comentarios /// no son texto muerto: rustdoc los compila en una web navegable con búsqueda, enlaces cruzados y tipos resaltados; sus ejemplos se ejecutan como pruebas —lo viste en el nivel de testing—; y docs.rs, un servicio neutral del ecosistema, construye y aloja esa documentación para cada versión publicada de cada crate, automáticamente, en cuanto haces cargo publish. El resultado es una norma cultural que casi ningún ecosistema logra: que toda librería tenga documentación hospedada, versionada e interconectada, generada desde su fuente real.

Los comentarios que son documentación

Rust distingue dos comentarios de documentación, y la diferencia es de dirección. /// documenta el elemento que le sigue; //! documenta el elemento que lo contiene, desde dentro —ideal para la portada de un módulo o del crate entero, en la cabecera de lib.rs—. El cuerpo es Markdown, y una convención de secciones tan asentada que funciona como vocabulario compartido:

//! # mi_crate
//!
//! Un parser tolerante a errores. Empieza por [`Parser::new`].

/// Analiza una cadena de configuracion.
///
/// # Examples
///
/// ```
/// # use mi_crate::Parser;
/// let cfg = Parser::new().parse("clave = 1")?;
/// assert_eq!(cfg.get("clave"), Some(&1));
/// # Ok::<(), mi_crate::Error>(())
/// ```
///
/// # Errors
///
/// Devuelve [`Error::Sintaxis`] si la entrada no es TOML valido.
///
/// # Panics
///
/// Entra en panico si se invoca antes de [`Parser::init`].
pub fn parse(&self, texto: &str) -> Result<Config, Error> { /* ... */ }

Esas cabeceras —# Examples, # Errors, # Panics, y para funciones unsafe, # Safety— no son adorno tipográfico. Son un contrato que todo Rustacean sabe leer: un lector experimentado busca directamente # Panics para saber qué hace estallar la función y # Safety para conocer las invariantes que debe garantizar. Y como aprendiste en la lección de doc-tests, el bloque bajo # Examples se compila y ejecuta: tu documentación no puede mentir sobre cómo se usa la API, porque el compilador la verifica en cada cargo test.

Enlaces intra-doc: la web que el compilador teje

La navegabilidad de la doc de Rust nace de una función que parece magia y es rigor: los enlaces intra-doc. Escribes el nombre de un tipo o método entre corchetes y rustdoc lo resuelve a su página, verificando que exista:

/// Convierte esto en un [`Config`], igual que [`Config::from_str`].
///
/// Si prefieres el camino perezoso, mira [`Parser::stream`] o
/// el modulo [`crate::io`]. Un enlace con texto: [la guia](crate::guia).
pub fn to_config(&self) -> Config { /* ... */ }

La clave: si renombras Config::from_str o lo eliminas, ese enlace rompe la compilación de la doc. No es un href estático que se pudre cuando el código evoluciona, sino una referencia resuelta contra el árbol real de símbolos, tan viva como una llamada a función. Combinado con los doc-tests, esto cierra el círculo: tanto lo que tu documentación afirma (los ejemplos) como lo que referencia (los enlaces) queda atado a la verdad del código.

Gobernar rustdoc con atributos

rustdoc se controla con atributos que van desde exigir documentación hasta esculpir qué se muestra. Los más útiles a la hora de mantener una librería seria:

#![warn(missing_docs)]                 // avisa de cada item publico sin documentar
#![doc(html_logo_url = "https://.../logo.svg")]

/// Detalle interno que la API expone por fuerza mayor, no para usarse.
#[doc(hidden)]
pub struct DetalleInterno;

/// Solo disponible con la feature `async`.
#[cfg(feature = "async")]
#[doc(cfg(feature = "async"))]        // muestra en la doc que exige esa feature
pub async fn parse_stream() { /* ... */ }

#![warn(missing_docs)] en la raíz del crate convierte cada pub sin documentar en una advertencia: la forma canónica de garantizar cobertura. #[doc(hidden)] esconde de la web lo que debe ser público en el sentido técnico pero no forma parte del contrato —lo que a menudo generan las macros—. Y #[doc(cfg(...))] renderiza una etiqueta que avisa: «esto solo existe si activas tal feature», resolviendo la confusión de una API que cambia de forma según la configuración.

docs.rs: la documentación como servicio del ecosistema

Aquí está el multiplicador. No tienes que generar ni alojar nada: cuando publicas en crates.io, el servicio docs.rs clona tu fuente, ejecuta cargo doc en un entorno reproducible y publica el resultado en https://docs.rs/mi_crate, con una página por cada versión que hayas subido. Documentación hospedada, versionada, uniforme y construida por un tercero neutral, gratis y para siempre. Puedes ajustar cómo la construye desde el manifiesto:

[package.metadata.docs.rs]
all-features = true                          # documenta con todas las features
rustdoc-args = ["--cfg", "docsrs"]           # activa el cfg para #[doc(cfg(...))]
targets = ["x86_64-unknown-linux-gnu"]       # o varios objetivos

Localmente, cargo doc --open genera y abre exactamente la misma web para tu crate y todas sus dependencias. La coherencia es el punto: la doc de serde, la tuya y la de cualquier crate transitivo se leen con la misma interfaz, se enlazan entre sí y se navegan igual.

flowchart TD
A[Escribes /// y //! en el codigo fuente] --> B[cargo doc genera la web local]
A --> C[cargo test ejecuta los ejemplos como doc-tests]
A --> D[cargo publish sube la fuente a crates.io]
D --> E[docs.rs clona y ejecuta cargo doc]
E --> F[Documentacion hospedada por version en docs.rs]
B --> G[Enlaces intra-doc verificados contra los simbolos]
style A fill:#cba6f7,color:#11111b
style C fill:#a6e3a1,color:#11111b
style F fill:#89b4fa,color:#11111b
style G fill:#f9e2af,color:#11111b