Pruebas de documentación
Ejemplos comprobados
Pruebas de documentación es una lección gratuita de Learn Rust Coding en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Learn Rust Coding, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Learn Rust Coding incluye 4 lecciones en total.
¿Qué son las pruebas de documentación?
Las pruebas de documentación son ejemplos de código dentro de comentarios de documentación que Cargo compila y ejecuta. Mantienen la documentación correcta y los ejemplos funcionales.
Código en los comentarios de documentación
Coloque el código de ejemplo en un bloque de código cercado (tres comillas invertidas) dentro de un comentario ///, bajo un encabezado # Examples. El lenguaje predeterminado es Rust.
/// Doubles a number.
///
/// # Examples
///
/// let result = my_crate::double(4);
/// assert_eq!(result, 8);
pub fn double(n: i32) -> i32 {
n * 2
}Ejecutar pruebas de documentación
Las pruebas de documentación se ejecutan como parte de cargo test. Se muestran por separado en una sección Doc-tests.
cargo testAserciones en los ejemplos
Los ejemplos suelen incluir aserciones para que un ejemplo incorrecto haga fallar la prueba, en lugar de limitarse a compilar.
/// Returns the larger of two values.
///
/// # Examples
///
/// assert_eq!(my_crate::max(3, 7), 7);
/// assert_eq!(my_crate::max(9, 2), 9);
pub fn max(a: i32, b: i32) -> i32 {
if a > b { a } else { b }
}Ocultar líneas de preparación
Anteponer # a una línea hace que se ejecute, pero que permanezca oculta en la documentación mostrada. Es útil para código repetitivo, como las importaciones.
/// # Examples
///
/// # use my_crate::Counter;
/// let mut c = Counter::new();
/// c.increment();
/// assert_eq!(c.value(), 1);Ejemplos que usan el signo de interrogación
Para usar el operador ?, incluya el cuerpo en un main oculto (o en un ayudante) que devuelva Result. Las líneas ocultas comienzan con #.
/// # Examples
///
/// # fn run() -> Result<(), std::num::ParseIntError> {
/// let n: i32 = "42".parse()?;
/// assert_eq!(n, 42);
/// # Ok(())
/// # }Ejemplos con no_run
Marque un bloque cercado con la anotación no_run para compilarlo sin ejecutarlo, algo práctico para ejemplos que necesitan acceder a la red o a archivos.
/// Fetches a page (compiled but not executed).
///
/// Annotate the code fence with no_run so it is type-checked only.
pub fn fetch(url: &str) -> String {
format!("contents of {url}")
}ignore y should_panic
Otras anotaciones para el bloque de código:
ignore— no se compila ni se ejecutashould_panic— se espera que entre en pánicocompile_fail— se espera que no compile
Por qué son importantes las pruebas de documentación
Las pruebas de documentación ofrecen dos beneficios a la vez:
- Documentación siempre precisa
- Cobertura de pruebas gratuita para los ejemplos públicos
Si un ejemplo deja de funcionar, el conjunto de pruebas falla.
Nombre del crate en los ejemplos
Las pruebas de documentación se ejecutan como si estuvieran fuera del crate, así que debe hacer referencia a los elementos mediante el nombre del crate (por ejemplo, my_crate::func) o una importación use.
Bloques cercados frente a bloques con sangría
Las pruebas de documentación admiten dos estilos de bloque:
- Un bloque cercado con tres comillas invertidas, que permite anotaciones como
no_run - Un bloque con sangría de cuatro espacios, como los que se muestran en estos ejemplos
Los bloques cercados son más habituales en el código real.
Comprobación rápida
¿Qué hace una línea que comienza con # dentro de un bloque de código de una prueba de documentación?
Resumen
Ha aprendido las pruebas de documentación:
- El código de los bloques
///es compilado y ejecutado porcargo test - Use aserciones para verificar el comportamiento
#oculta las líneas de preparación en la documentación mostrada- Anotaciones:
no_run,ignore,should_panic,compile_fail - Mantienen los ejemplos correctos automáticamente
Preguntas frecuentes
¿La lección «Pruebas de documentación» es gratis?
Sí — el texto completo de «Pruebas de documentación» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Learn Rust Coding, actualiza a CoddyKit PRO. El curso de Learn Rust Coding incluye 4 lecciones en total.
¿Qué aprenderé en «Pruebas de documentación»?
Ejemplos comprobados Practicas Learn Rust Coding con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar Learn Rust Coding?
No se requiere experiencia previa. Learn Rust Coding en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.
¿Cuánto tiempo toma la lección «Pruebas de documentación»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de Learn Rust Coding?
Sí. Cada lección de Learn Rust Coding incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Pruebas unitarias
- Pruebas de integración
- Comentarios de documentación
- Pruebas de documentación