La documentació és una part essencial del desenvolupament de programari, ja que ajuda a altres desenvolupadors (i a tu mateix en el futur) a comprendre el codi, les seves funcionalitats i com utilitzar-lo. Rust proporciona eines potents per crear documentació de manera eficient i integrada amb el codi.
- Comentaris de Documentació
Rust utilitza comentaris especials per generar documentació. Aquests comentaris es col·loquen just abans de l'element que es vol documentar (funcions, structs, mòduls, etc.) i comencen amb tres barres (///).
Exemple de Comentaris de Documentació
/// Aquesta funció suma dos nombres enters.
///
/// # Arguments
///
/// * `a` - Un nombre enter.
/// * `b` - Un altre nombre enter.
///
/// # Retorna
///
/// La suma de `a` i `b`.
fn suma(a: i32, b: i32) -> i32 {
a + b
}Explicació
///indica que el text següent és un comentari de documentació.- La secció
# Argumentsdescriu els paràmetres de la funció. - La secció
# Retornadescriu el valor de retorn de la funció.
- Generació de Documentació amb
rustdoc
rustdocRust inclou una eina anomenada rustdoc que genera documentació HTML a partir dels comentaris de documentació del codi.
Com Generar Documentació
- Navega al directori del teu projecte.
- Executa la següent comanda:
Aquesta comanda generarà la documentació i l'obrirà en el teu navegador web per a la seva visualització.
- Documentació de Mòduls
Els mòduls també poden ser documentats utilitzant comentaris de documentació. Aquests comentaris es col·loquen just abans de la declaració del mòdul.
Exemple de Documentació de Mòduls
/// Aquest mòdul conté funcions matemàtiques bàsiques.
pub mod matematiques {
/// Aquesta funció suma dos nombres enters.
pub fn suma(a: i32, b: i32) -> i32 {
a + b
}
/// Aquesta funció resta dos nombres enters.
pub fn resta(a: i32, b: i32) -> i32 {
a - b
}
}
- Proves de Documentació
Rust permet incloure exemples de codi dins dels comentaris de documentació, que es poden executar com a proves per assegurar-se que els exemples funcionen correctament.
Exemple de Proves de Documentació
/// Aquesta funció multiplica dos nombres enters.
///
/// # Exemple
///
/// ```
/// let resultat = multiplica(2, 3);
/// assert_eq!(resultat, 6);
/// ```
fn multiplica(a: i32, b: i32) -> i32 {
a * b
}Executar Proves de Documentació
Per executar les proves de documentació, utilitza la següent comanda:
Aquesta comanda executarà totes les proves, incloent les proves de documentació.
- Enllaços i Format de la Documentació
Rust permet utilitzar enllaços i formatar el text dins dels comentaris de documentació per fer-los més llegibles i útils.
Exemple d'Enllaços i Format
/// Aquesta funció divideix dos nombres enters.
///
/// # Arguments
///
/// * `a` - Un nombre enter.
/// * `b` - Un altre nombre enter.
///
/// # Retorna
///
/// La divisió de `a` per `b`.
///
/// # Panics
///
/// Aquesta funció farà `panic` si `b` és zero.
///
/// # Exemple
///
/// ```
/// let resultat = divideix(6, 3);
/// assert_eq!(resultat, 2);
/// ```
///
/// Per més informació, consulta la [documentació oficial de Rust](https://doc.rust-lang.org).
fn divideix(a: i32, b: i32) -> i32 {
if b == 0 {
panic!("No es pot dividir per zero!");
}
a / b
}Exercici Pràctic
Exercici
Crea una funció anomenada potencia que calculi la potència d'un nombre enter elevat a un altre nombre enter. Documenta la funció utilitzant comentaris de documentació, incloent una descripció, els arguments, el valor de retorn, un exemple i una secció de panics si és necessari.
Solució
/// Aquesta funció calcula la potència d'un nombre enter elevat a un altre nombre enter.
///
/// # Arguments
///
/// * `base` - El nombre base.
/// * `exponent` - L'exponent al qual s'eleva la base.
///
/// # Retorna
///
/// La potència de `base` elevat a `exponent`.
///
/// # Exemple
///
/// ```
/// let resultat = potencia(2, 3);
/// assert_eq!(resultat, 8);
/// ```
///
/// # Panics
///
/// Aquesta funció farà `panic` si l'exponent és negatiu.
fn potencia(base: i32, exponent: i32) -> i32 {
if exponent < 0 {
panic!("L'exponent no pot ser negatiu!");
}
let mut resultat = 1;
for _ in 0..exponent {
resultat *= base;
}
resultat
}Conclusió
La documentació és una part crucial del desenvolupament de programari, i Rust proporciona eines potents per crear documentació clara i útil. Utilitzant comentaris de documentació, rustdoc i proves de documentació, pots assegurar-te que el teu codi és ben documentat i fàcil de comprendre per altres desenvolupadors.