started working on comments and stuff

book/src/SUMMARY.md

@@ -7,3 +7,4 @@
 - [Part 02](./part02.md)
 - [Part 03](./part03.md)
 - [Part 04](./part04.md)
+- [Part 05](./part05.md)

book/src/part05.md

+# 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

codes/rust_lang/part05/src/main.rs

-/*!
-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