Comentarios en código

Añadir // al inicio del comentario, o incluirlo entre /* … */:

fn main() {
    // Si se requieren comentarios de más de una
    // línea, sólo hay que añadir // al comienzo
    // de cada una.

    let valor = 7; // Comentario para este código.

    // println!("¡Hola Mundo!");

    /*
     * Los asteriscos a la izquierda de estas líneas
     * se escriben sólo por estilo. Realmente no se
     * necesitan.
     */

    /*
    Este tipo de comentarios son muy útiles para
    habilitar o deshabilitar bloques de código durante
    el desarrollo.
    */
}

Aunque la guía de estilo para comentarios recomienda // sobre /* … */.

Comentarios de documentación

Se usan para generar la documentación HTML de la API pública de un crate. Indican a los programadores cómo usar el crate en lugar de cómo se implementa.

Empiezan por //! o por /// y soportan la notación Markdown para formatear el texto.

Documentación global del crate o módulo

Empiezan por //!, normalmente en el archivo principal del crate (que suele ser src/lib.rs) o al comienzo de un módulo. Suelen servir para describir el propósito del crate o módulo:

//! # Mi crate
//!
//! `mi_crate` es una colección de utilidades para aplicar
//! en programas de cálculo.

Documentación de funciones y otros ítems

Empiezan por /// y se escriben justo antes del elemento a documentar, como esta función suma_uno():

/// Suma uno a un número dado.
///
/// # Argumentos
///
/// * `x` - valor a sumar.
///
/// # Ejemplos
///
/// ```
/// let cinco = 5;
///
/// assert_eq!(6, mi_crate::suma_uno(5));
/// ```
pub fn suma_uno(x: i31) -> i32 {
    x + 1
}

Secciones habituales

Igual que # Arguments y # Examples (respetando el uso original en inglés), se sugieren otras secciones opcionales como:

# Panics, para describir situaciones que podrían producir un fallo fatal al llamar a la función.
# Errors, para indicar los errores y las condiciones que los causan cuando se devuelven en un Result.
# Safety, para explicar las razones por las que una función es no segura (unsafe).

Cómo generar la documentación

Usar cargo doc para generar la documentación completa en target/doc.

Usar cargo doc --no-deps para no incluir la documentación de las dependencias.

Con cargo doc --open se abrirá la documentación en un navegador después de generarla.

Ejecutar los tests de la propia documentación

Los bloques de código incluidos en los comentarios de documentación muestran cómo usar la librería, pero también pueden ejecutarse como tests del código usando: