Comentarios de documentación
Documentación con ///
Comentarios de documentación es una lección gratuita de Learn Rust Coding en CoddyKit. Esta es la lección 3 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.
Documentación en Rust
Rust incorpora documentación de primera clase en el lenguaje. Los comentarios especiales se convierten en documentación HTML generada por cargo doc.
Comentarios de documentación externos
Use /// para documentar el elemento que aparece después: funciones, estructuras, enumeraciones y otros. El texto admite Markdown.
/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
a + b
}Formato Markdown
Los comentarios de documentación se representan como Markdown: funcionan los encabezados, las listas, la negrita y los enlaces. El código en línea usa comillas invertidas y los encabezados de sección comienzan con #.
/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
width * height
}Secciones habituales de la documentación
Los encabezados convencionales facilitan la lectura rápida de la documentación:
# Examples— ejemplos de uso# Panics— cuándo entra en pánico# Errors— qué errores devuelve# Safety— invariantes del código no seguro
Comentarios de documentación internos
Use //! para documentar el elemento contenedor, normalmente un módulo o el crate completo. Colóquelo al principio del archivo.
//! # My Math Crate
//!
//! Utilities for basic arithmetic.
pub fn double(n: i32) -> i32 {
n * 2
}Documentar estructuras y campos
Cada elemento público, incluidos los campos de una estructura, puede tener su propio comentario de documentación.
/// A point in 2D space.
pub struct Point {
/// The horizontal coordinate.
pub x: f64,
/// The vertical coordinate.
pub y: f64,
}Generar documentación
cargo doc crea la documentación HTML en target/doc. Añada --open para verla en el navegador.
cargo doc --openExcluir dependencias
De forma predeterminada, Cargo también documenta las dependencias. Use --no-deps para generar documentación únicamente para su crate.
cargo doc --no-deps --openEnlaces entre elementos de la documentación
Enlace a otros elementos escribiendo su ruta entre corchetes. Rust resuelve la ruta y crea un enlace en el que se puede hacer clic en la documentación generada.
/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
a - b
}¿Por qué documentar?
Una buena documentación ofrece grandes beneficios:
- Se genera automáticamente como HTML con función de búsqueda
- Se publica gratis en docs.rs al publicar un crate
- Los ejemplos de la documentación se prueban (pruebas de documentación)
- Ayuda a sus compañeros y a su yo del futuro
Documentar un módulo
Combine comentarios internos y externos: un archivo de módulo comienza con //! para describir el módulo, y cada elemento interno usa ///.
//! Geometry helpers.
/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
side * 4.0
}Comprobación rápida
¿Qué sintaxis de comentario documenta el elemento que aparece justo después?
Resumen
Ha aprendido los comentarios de documentación:
///documenta el elemento siguiente;//!documenta el elemento contenedor- Admiten Markdown y secciones como
# Examples - Los enlaces entre elementos conectan distintos elementos
cargo doc --opengenera y muestra documentación HTML
Preguntas frecuentes
¿La lección «Comentarios de documentación» es gratis?
Sí — el texto completo de «Comentarios 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 «Comentarios de documentación»?
Documentación con /// 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 3 de 4.
¿Cuánto tiempo toma la lección «Comentarios 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