19. Divers▲
Certaines sections ne sont pas tout à fait liées à la manière dont vous programmez mais vous introduisent et fournissent des outils facilitant les choses pour tout le monde. Ces sections abordent :
- La documentation : Générez la documentation d'une bibliothèque pour les utilisateurs via rustdoc ;
- Les tests : Créez des suites de tests pour garantir l'intégrité de vos bibliothèques ;
- Les benchmarks : Créez des benchmarks de vos fonctionnalités pour garantir leur performance.
19-1. Documentation▲
Les commentaires de documentation sont très utiles pour d'importants projets nécessitant une documentation. Lorsque vous lancez Rustdoc, ce sont ces commentaires qui seront compilés dans la documentation. Ils sont préfixés par la séquence /// et supportent Markdown.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
// #![crate_name = "doc"]
/// Un être humain est représenté ici.
pub struct Person {
/// Une personne doit avoir un nom.
name: String,
}
impl Person {
/// Renvoie une personne avec le nom qu'on lui a donné.
///
/// # Arguments
///
/// * `name` - Une slice qui contient le nom de la personne.
///
/// # Example
///
/// ```
/// // Vous pouvez écrire du code rust entre les balises
/// // dans les commentaires.
/// // Si vous passez --test à Rustdoc, il testera même la source pour vous !
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
Person { name: name.to_string() }
}
/// Affiche un salut amical !
///
/// Affiche "Hello, [name]" à l'objet `Person` en question.
pub fn hello(&self) {
println!("Hello, {}!", self.name);
}
}
fn main() {
let john = Person::new("John");
john.hello();
}
Note : si vous souhaitez compiler ce programme vous-même, n'oubliez pas de décommenter la ligne // #![crate_name = "doc"].
Pour lancer les tests, vous devez tout d'abord compiler le code en mode bibliothèque puis renseigner la position de la bibliothèque à rustdoc pour qu'il puisse la lier à chaque programme de la documentation :
rustc doc.rs --crate-type lib
rustdoc --test --extern doc="libdoc.rs"Lorsque vous exécutez la commande cargo test sur une crate, Cargo générera et exécutera automatiquement les commandes respectives de rustc et rustdoc.
19-2. Tests▲
Les fonctions peuvent être testées en utilisant ces attributs:
#[test]désigne une fonction comme test unitaire. La fonction ne doit prendre aucun paramètre et ne rien renvoyer ;#[should_panic]désigne une fonction comme un test voué à l'échec.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
// Dans le fichier unit_test.rs
// Compile `main` à condition que la compilation des tests ne soit pas activée.
#[cfg(not(test))]
fn main() {
println!("If you see this, the tests were not compiled nor ran!");
}
// Compile le module `test` seulement si la compilation des tests est activée.
#[cfg(test)]
mod test {
// Un test unitaire `distance_test` est nécessaire.
fn distance(a: (f32, f32), b: (f32, f32)) -> f32 {
(
(b.0 - a.0).powi(2) +
(b.1 - a.1).powi(2)
).sqrt()
}
#[test]
fn distance_test() {
assert!(distance((0f32, 0f32), (1f32, 1f32)) == (2f32).sqrt());
}
#[test]
#[should_panic]
fn failing_test() {
assert!(1i32 == 2i32);
}
}
Les tests peuvent être exécutés avec la commande cargo test ou rustc --test.
2.
3.
4.
5.
6.
7.
8.
$ rustc --test unit_test.rs
$ ./unit_test
running 2 tests
test test::distance_test ... ok
test test::failing_test ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured
Si --test n'a pas été inclut alors il devrait se passer ceci :
$ rustc unit_test.rs
$ ./unit_test
If you see this, the tests were not compiled nor ran!Voir aussi
