From 5d8eb026b47e0404ad911aa55b110ed50396d1e6 Mon Sep 17 00:00:00 2001 From: Orestis <orestis.malaspinas@pm.me> Date: Fri, 14 Jul 2023 12:01:19 +0200 Subject: [PATCH] started working on comments and stuff --- book/src/SUMMARY.md | 1 + book/src/part05.md | 108 +++++++++++++++++++++++++++++ codes/rust_lang/part05/src/main.rs | 92 ++++++++++++------------ 3 files changed, 158 insertions(+), 43 deletions(-) create mode 100644 book/src/part05.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index e3ee109..80087bd 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 0000000..8048b4d --- /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 936bf3c..163cc13 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 -- GitLab