Utiliser examples/ pour des tests (exemples) documentaires

En principe, Rust prévoit qu’il n’y a qu’un seul fichier librairie dans un projet (crate), par défaut le fichier src/lib.rs.

Nous pouvons toutefois effectuer des tests sur des bouts de codes de librairies et de tests documentaires indépendants en suivant le protocole suivant.

Paramétrage dans Cargo.toml

[lib]

[[example]]
name = "lib_exemple"
path = "examples/lib_exemple/lib.rs"
crate-type = ["lib"]
doctest = true

Fichier src/lib.rs

#![allow(unused)]
fn main() {
#[doc(hidden)]
#[path = "../examples/lib_exemple/lib.rs"]
pub mod lib_exemple;
}

Nous déclarons le module avec le chemin vers notre fichier isolé. Pour éviter les conflits et / ou pour éviter qu’il ne soit publié avec la documentation de l’API du projet en cours, nous le déclarons caché pour la documentation.

Fichier examples/lib_exemple/lib.rs

#![allow(unused)]
fn main() {
/// ```
/// use rust_divers::lib_exemple::ajouter;
/// 
/// let a: i32 = 5_i32;
/// let b: i32 = 2_i32;
/// let resultat: i32 = ajouter(a, b);
/// assert_eq!(resultat, 7_i32);
/// ```
pub fn ajouter(a: i32, b: i32) -> i32 {
    a + b // Expression de retour (pas de point-virgule)
}
}

Nous nous servons de la syntaxe habituelle pour les exemples documentaires de Rust.

Au niveau de l’import (use) :

• rust_divers est le nom du projet,
• lib_exemple est le nom de la librairie tel que nous l’avons défini dans src/lib.rs et
• ajouter est le nom de la fonction sur laquelle porte notre exemple (et test unitaire).

Exécution

La commande habituelle

cardo test --doc

exécute le test contenu dans examples/lib_exemple/lib.rs.

Retour :

   Compiling rust-divers v0.1.0 (/home/user/mesprojets/rust-divers)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.00s
   Doc-tests rust_divers

running 1 test
test src/../examples/lib_exemple/lib.rs - lib_exemple_test::ajouter (line 1) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

all doctests ran in 0.60s; merged doctests compilation took 0.59s