Documentación en Rust: técnicas avanzadas y herramientas

Introducción: Por qué la documentación en Rust es más que comentarios

El ecosistema de Rust es conocido por su rigor y fiabilidad. Sin embargo, incluso el código más elegante es inútil sin una documentación de calidad. A nivel básico, basta con escribir un par de líneas /// para funciones públicas. Pero cuando tu proyecto crece hasta abarcar varios crates con decenas de módulos, surge la cuestión de las técnicas avanzadas de documentación.

En este artículo, exploraremos herramientas y técnicas que te ayudarán a crear documentación de nivel empresarial: desde pruebas automáticas de ejemplos hasta generación de libros e integración con CI/CD.

1. Doctests: documentación que no miente

La principal característica de rustdoc es la capacidad de incrustar ejemplos de código ejecutables directamente en los comentarios. Estos ejemplos se compilan y ejecutan automáticamente al ejecutar cargo test. Esto garantiza que tu documentación esté siempre actualizada.

Doctest básico

/// Devuelve la suma de dos números.\n///\n/// # Ejemplo\n///\n/// ```\n/// let result = my_crate::add(2, 3);\n/// assert_eq!(result, 5);\n/// ```\npub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}

Técnicas avanzadas con doctest

Puedes ocultar líneas de preparación que no deben mostrarse en la documentación usando # :

/// # Ejemplo con inicialización\n///\n/// ```\n/// # use std::collections::HashMap;\n/// let mut map = HashMap::new();\n/// map.insert("key", 42);\n/// assert_eq!(map.get("key"), Some(&42));\n/// ```

También puedes verificar que el código no compile (por ejemplo, para demostrar errores en tiempo de compilación):

/// ```compile_fail\n/// let x: i32 = "cadena"; // Error: tipo incompatible\n/// ```

2. Atributos de documentación: control y metadatos

Los atributos #[doc(...)] permiten ajustar finamente la visualización de la documentación.

Ocultar elementos

/// Función interna, no destinada para uso público.\n#[doc(hidden)]\npub fn internal_helper() {}

Categorización y búsqueda

/// Grupo de utilidades para trabajar con redes.\n#[doc(alias = "net")]\n#[doc(alias = "socket")]\npub mod network {\n    // ...\n}

Incrustar documentación desde otra ubicación

/// Consulte la [documentación del módulo](index.html) para información general.\n#[doc(include = "docs/faq.md")]\npub fn complex_function() {}

3. Referencias cruzadas y navegación

Rustdoc admite enlaces a otros elementos de la documentación. Esto crea una estructura coherente y fácil de leer.

Enlaces a funciones y tipos

/// Use [`Config::new`] para crear una instancia.\n///\n/// Para una configuración más compleja, consulte el módulo [`config`].\npub struct Config { /* ... */ }

Enlaces a crates externos

/// Esta función utiliza [serde_json] para la serialización.\n///\n/// [serde_json]: https://docs.rs/serde_json\npub fn to_json() {}

4. Herramientas para proyectos grandes: mdBook y documentación de crates

Cuando un solo cargo doc ya no es suficiente, mdBook viene al rescate: una utilidad para crear libros a partir de archivos Markdown. Es ideal para escribir guías, tutoriales y documentación arquitectónica.

Inicio rápido con mdBook

# Instalación\ncargo install mdbook\n\n# Crear proyecto\nmdbook init my-book\ncd my-book\nmdbook serve --open

Integración con rustdoc

Puede incrustar documentación de mdBook en cargo doc usando el atributo #[doc = include_str!()]:

/// # Arquitectura\n///\n/// Descripción detallada de la arquitectura de la biblioteca:\n///\n#[doc = include_str!("../docs/architecture.md")]\npub mod core {\n    // ...\n}

Conclusión