La documentación es una parte esencial del desarrollo de software, ya que facilita la comprensión y el uso del código tanto para los desarrolladores actuales como para los futuros. En Rust, la documentación se integra directamente en el código fuente, lo que permite mantener la documentación y el código sincronizados. En este tema, aprenderemos cómo documentar el código en Rust utilizando comentarios de documentación y herramientas como rustdoc.
- Comentarios de Documentación
Rust utiliza comentarios especiales para generar documentación. Estos comentarios se escriben con tres barras (///) y se colocan justo antes de la declaración del elemento que se está documentando (funciones, structs, módulos, etc.).
Ejemplo Básico
/// Esta función suma dos números y devuelve el resultado.
///
/// # Ejemplos
///
/// ```
/// let resultado = sumar(2, 3);
/// assert_eq!(resultado, 5);
/// ```
fn sumar(a: i32, b: i32) -> i32 {
a + b
}Explicación
///indica que el comentario es parte de la documentación.- La descripción de la función se coloca inmediatamente después de las barras.
- La sección
# Ejemplosproporciona ejemplos de uso de la función, que se pueden ejecutar como pruebas.
- Secciones de Documentación
Rust permite varias secciones en los comentarios de documentación para estructurar la información de manera clara y útil.
Secciones Comunes
- Descripción: Una breve descripción de lo que hace el elemento.
- Parámetros: Descripción de los parámetros de la función.
- Retorno: Descripción del valor de retorno.
- Ejemplos: Ejemplos de uso del elemento.
- Panics: Situaciones en las que la función puede causar un pánico.
- Errors: Errores que pueden ser devueltos por la función.
Ejemplo Completo
/// Calcula el factorial de un número no negativo.
///
/// # Parámetros
///
/// - `n`: Un número entero no negativo.
///
/// # Retorno
///
/// El factorial de `n`.
///
/// # Panics
///
/// La función hará pánico si `n` es negativo.
///
/// # Ejemplos
///
/// ```
/// let resultado = factorial(5);
/// assert_eq!(resultado, 120);
/// ```
fn factorial(n: i32) -> i32 {
if n < 0 {
panic!("El número no puede ser negativo");
}
(1..=n).product()
}
- Generación de Documentación con
rustdoc
rustdocRust incluye una herramienta llamada rustdoc que genera documentación HTML a partir de los comentarios de documentación en el código fuente.
Generar Documentación
Para generar la documentación, ejecuta el siguiente comando en la terminal:
Este comando generará la documentación en formato HTML y la almacenará en el directorio target/doc.
Ver la Documentación
Para ver la documentación generada, abre el archivo index.html en el navegador:
- Documentación de Módulos
Además de documentar funciones y structs, también es importante documentar módulos. Los comentarios de documentación para módulos se colocan al principio del archivo del módulo o dentro de un bloque //!.
Ejemplo de Documentación de Módulo
//! Este módulo proporciona funciones matemáticas básicas.
//!
//! # Ejemplos
//!
//! ```
//! let suma = math::sumar(2, 3);
//! assert_eq!(suma, 5);
//! ```
pub mod math {
/// Suma dos números.
pub fn sumar(a: i32, b: i32) -> i32 {
a + b
}
}
- Ejercicio Práctico
Ejercicio
Documenta la siguiente función utilizando los conceptos aprendidos:
fn dividir(a: f64, b: f64) -> Result<f64, String> {
if b == 0.0 {
Err(String::from("No se puede dividir por cero"))
} else {
Ok(a / b)
}
}Solución
/// Divide dos números y devuelve el resultado.
///
/// # Parámetros
///
/// - `a`: El numerador.
/// - `b`: El denominador.
///
/// # Retorno
///
/// Un `Result` que contiene el resultado de la división si `b` no es cero, o un mensaje de error si `b` es cero.
///
/// # Ejemplos
///
/// ```
/// let resultado = dividir(10.0, 2.0).unwrap();
/// assert_eq!(resultado, 5.0);
///
/// let error = dividir(10.0, 0.0).unwrap_err();
/// assert_eq!(error, "No se puede dividir por cero");
/// ```
fn dividir(a: f64, b: f64) -> Result<f64, String> {
if b == 0.0 {
Err(String::from("No se puede dividir por cero"))
} else {
Ok(a / b)
}
}Conclusión
La documentación es una herramienta poderosa en Rust que ayuda a mantener el código comprensible y utilizable. Utilizando comentarios de documentación y rustdoc, puedes crear documentación clara y útil directamente desde tu código fuente. Asegúrate de documentar todas las funciones, structs y módulos para que otros desarrolladores (y tú mismo en el futuro) puedan entender y utilizar tu código de manera efectiva.
Curso de Programación en Rust
Módulo 1: Introducción a Rust
- ¿Qué es Rust?
- Configuración del Entorno de Rust
- Programa "Hola, Mundo!"
- Sintaxis y Estructura Básica