diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index e3ee109776442d822fe11371f8181ec9f7d553e0..80087bd74e0b5d7cd9327dd7befd4a3deac892a4 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -7,3 +7,4 @@ - [Part 02](./part02.md) - [Part 03](./part03.md) - [Part 04](./part04.md) +- [Part 05](./part05.md) diff --git a/book/src/part05.md b/book/src/part05.md new file mode 100644 index 0000000000000000000000000000000000000000..8048b4da10162d536e0c915952ce56add5bc396c --- /dev/null +++ b/book/src/part05.md @@ -0,0 +1,108 @@ +# Discussion du code `part05` + +Dans cette partie nous discutons de [ce code](#le-code). + +## Concepts + +Les concepts abordés dans cet exemple sont: + +1. [La documentation.](#la-documentation) +2. [Les tests.](#les-tests) +3. [Les tests de documentation.](#les-tests-de-documentation) +4. [Les outils en plus du compilateur](#les-outils-en-plus-du-compilateur) + +## Discussion + +Le Rust étant un langage moderne, il vient avec tout un tas de features qui sont très appréciables pour écrire du code robuste, propre et réutilisable. On va voir quelle est la syntaxe nécessaire pour écrire documentation et tests. + +### La documentation + +Il y a différents moyens de documenter un code. Pour un guide bien plus complet que ce qui est résumé ici, vous pouvez vous référer à [ce site](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html). + +#### Les commentaires + +Le plus simple est d'y ajouter des commentaires. En Rust, tous caractères qui suivent des `//` sur la même ligne sont considérés comme un commentaire (ignorés par le compilateur) + +```rust,no_run +// Ceci est un commentaire +// Et ceci un autre +let a = 2; // Ici on assigne 2 à a +``` + +On peut écrire également des commentaires sur plusieurs lignes sans avoir à mettre des `//` sur chacune. Pour ce faire on utilise la syntaxe `/* ... */` + +```rust,no_run +/* + Ceci est un commentaire + Et ceci un autre + Et en voici un dernier +*/ +let a = 2; /* Ici on assigne 2 à a */ +``` + +Ce type de documentation se prête très bien à des commentaires sur les détails du code, mais n'est pas très adapté à écrire une documentation plus générale sur le comportement du code. Ainsi, on a autre type de commentaires, qui seront utilisés pour générer automatiquement de la documentation à l'aide de l'outil `rustdoc`. + +#### La documentation par composants + +La documentation d'un composant, que ça soit une `struct`, un `enum`, une fonction, etc. se fait en préfixant `///` devant la ligne de documentation et la plaçant +directement au dessus du composant à commenter. Ainsi les exemples suivants permettent de: + +* Documenter une constante + +```rust,ignore +{{#include ../../codes/rust_lang/part05/src/main.rs:size}} +``` + +* Documenter une fonction + +```rust,ignore +{{#include ../../codes/rust_lang/part05/src/main.rs:function}} +``` + +* Documenter une fonction statique + +```rust,ignore +{{#include ../../codes/rust_lang/part05/src/main.rs:static_function}} +``` + +* Documenter un trait + +```rust,ignore +{{#include ../../codes/rust_lang/part05/src/main.rs:minimum}} +``` + +* Documenter un type énuméré et ses variantes + +```rust,ignore +{{#include ../../codes/rust_lang/part05/src/main.rs:something_or_nothing}} +``` + +#### La documentation d'une `crate` + +Une librairie est appelée `crate` Rust. Afin de donner des informations de haut niveau +sur le fonctionnement d'une librairie, on peut utiliser une syntaxe spéciale `//!` à mettre au début de chaque +ligne de documentation (on peut également utiliser la syntaxe `/*! ... */`), comme ci-dessous + +```rust,ignore +{{#include ../../codes/rust_lang/part05/src/main.rs:crate}} +``` + +#### Markdown + +La documentation supporte la syntaxe du [Common Markdown](https://commonmark.org/) + +#### Génération de la documentation + +Tout ce travail + +### Les tests + +### Les tests de documentation + +### Les outils en plus du compilateur + +## Le code + +```rust +{{#rustdoc_include ../../codes/rust_lang/part05/src/main.rs:main}} +``` \ No newline at end of file diff --git a/codes/rust_lang/part05/src/main.rs b/codes/rust_lang/part05/src/main.rs index 936bf3c28f8e4386d0aff407f4d8d6d4f330f27e..163cc130f4cd2bd9b4c93e45f9432b49acbc5cf7 100644 --- a/codes/rust_lang/part05/src/main.rs +++ b/codes/rust_lang/part05/src/main.rs @@ -1,42 +1,40 @@ -/*! -This is an example of Rust crate comments (or inner comments). -They will be rendered in the front page of your (crate) library. - -In this program we wrote an algorithm that computes the minimum of -a sequence of integers. - -To create the documentation run the command -```bash -cargo doc -``` -The obtain documentation can be found in the `target/doc/part04/index.html` directory - -To view the documentation type -```bash -cargo doc --open -``` -which will open the browser and show you the documentation. - -The documentation supports the CommonMarkdown syntax. - -Below we will use the `///` comments that will comment the code directly below. -We can also sue `//` but they will not be rendered. -Each line written here could be prefixed by `//!` instead of enclosed in `/*! */`. - -For more informations about writing documentation [follow that link](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html). - -Also Rust comes with great tooling. -- Clippy: A linter. -- Rustfmt: A formatter. -*/ - -// Rust basics: -// - Tests -// - Copy/Clone via derive -// - PartialEq -// - Documentation -// - clippy, rustfmt - +// ANCHOR: crate +//! This is an example of Rust crate comments (or inner comments). +//! They will be rendered in the front page of your (crate) library. +//! +//! # How to generate the documentation +//! +//! In this program we wrote an algorithm that computes the minimum of +//! a sequence of integers. +//! +//! To create the documentation run the command +//! ```bash +//! cargo doc +//! ``` +//! The obtain documentation can be found in the `target/doc/part05/index.html` directory +//! +//! To view the documentation type +//! ```bash +//! cargo doc --open +//! ``` +//! which will open the browser and show you the documentation. +//! +//! The documentation supports the CommonMarkdown syntax. +//! +//! Below we will use the `///` comments that will comment the code directly below. +//! We can also sue `//` but they will not be rendered. +//! All the lines written here could be enclosed in `/*! ... */` instead of being prefixed by `//!`. +//! +//! For more informations about writing documentation [follow that link](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html). +//! +//! # Tooling +//! +//! Also Rust comes with great tooling. +//! - Clippy: A linter. +//! - Rustfmt: A formatter. +// ANCHOR_END: crate + +// ANCHOR: something_or_nothing /// An generic enumerated type that has two variants that are [Clone] /// and [Copy] using derive. /// @@ -49,6 +47,7 @@ enum SomethingOrNothing<T> { /// A [SomethingOrNothing::Something] encapsulating a T Something(T), } +// ANCHOR_END: something_or_nothing impl<T: std::fmt::Display> SomethingOrNothing<T> { /// A static function that prints the content of a SomethingOrNothing. @@ -60,12 +59,14 @@ impl<T: std::fmt::Display> SomethingOrNothing<T> { } } +// ANCHOR: static_function impl<T> Default for SomethingOrNothing<T> { /// By Default a [SomethingOrNothing] is a nothing. fn default() -> Self { SomethingOrNothing::Nothing } } +// ANCHOR_END: static_function impl<T: PartialEq> PartialEq for SomethingOrNothing<T> { fn eq(&self, other: &Self) -> bool { @@ -79,11 +80,12 @@ impl<T: PartialEq> PartialEq for SomethingOrNothing<T> { } } -// If we remove Copy, we have a problem with the t in tab -// in the computation of the minimum. +// ANCHOR: minimum +/// The [Minimum] trait computes the minimum value between two values of a type trait Minimum: Copy { fn min(self, rhs: Self) -> Self; } +// ANCHOR_END: minimum impl<T: Minimum> Minimum for SomethingOrNothing<T> { fn min(self, rhs: Self) -> Self { @@ -104,8 +106,7 @@ impl<T: Minimum> Minimum for SomethingOrNothing<T> { } } -// i32 is Copyable as a very basic type as f32, f64, etc. -// Arrays for example are not copyable. +// Since i32 is [Copy] we don't need to explicitly implement it for i32 impl Minimum for i32 { fn min(self, rhs: Self) -> Self { if self < rhs { @@ -116,12 +117,17 @@ impl Minimum for i32 { } } +// ANCHOR: size +/// A constant that is the size of const SIZE: usize = 9; +// ANCHOR_END: size +// ANCHOR: function /// Poorly emulates the parsing of a command line. fn read_command_line() -> [i32; SIZE] { [10, 32, 12, 43, 52, 53, 83, 2, 9] } +// ANCHOR_END: function /// Prints all the elements of the `tab`. /// Tab is borrowed here