diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..1e08526 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,7 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 3 + +[[package]] +name = "burritos" +version = "0.1.0" diff --git a/doc/DOCUMENTATION.md b/doc/DOCUMENTATION.md new file mode 100644 index 0000000..81c15e1 --- /dev/null +++ b/doc/DOCUMENTATION.md @@ -0,0 +1,196 @@ +# Comment utiliser la documentation Rust + +![](https://www.rust-lang.org/static/images/rust-social-wide.jpg) + +## Écrire un commentaire en Rust + +Pour écrire un commentaire qui apparaitra sur la doc de cargo, écrivez : + +```rust +/// Votre commentaire +``` +pour commenter votre fonction, attribut, structure, module.... + +Pour les commentaires de **crate**, utilisez : + +```rust +//! Votre commentaire +``` + +*Les commentaires style java (`/** */`) sont supporté à l'exception des règles `@` **mais utilisez plutôt les commentaires standard de rust please***. + +Vous pouvez ensuite écrire votre commentaire comme bon vous semble; la documentation supporte le markdown, n'hésitez surtout pas à mettre des h3, des textes den gras, des exemple encapsulé, etc. + +Petit aide avec la markdown dans le chapitre [#aide-markdown](#aide-markdown). + + +### Exemple + +Vous obtenez quelque chose sur votre code comme à la figure 1. + +![Capture d'écran de main.rs](Screenshot_20221019_153737.png "Aperçu du main") + + +## Générer la documentation Rust + +Éxecutez la commande __`cargo doc`__ dans le dossier du projet, cela va générer un dossier dans le dossier **target/doc/** qui contient des pages web, ouvrez le fichier **target/doc/burritos/all.html**. + +Lors de l'affichage de la liste de vos fonctions et autres éléments, la doc **n'affiche que la première ligne**, le autres lignes sont affiché lorsqu'on ouvre les détails. + +### Exemple + +En partant du code de la figure 1, vous obtenez une documentation comme aux figures 2 et 3. + +!["Page d'accueil de la doc"](Screenshot_20221019_153803.png "Page all.html de la crate burritos généré à partir de l'exemple de la figure 1") + +!["Page de la fonction main de la doc"](Screenshot_20221019_153817.png "Page de la fonction main") + + +## Aide markdown + +Comme le markdown est utile pour écrire et mettre en page des commentaire en Rust, petit tuto sur comment formaté du texte en markdown. + +lorsque vous voulez passer à la ligne, faites 2 sauts à la ligne en markdown (oui pas une blague), un saut à la ligne sur le fichier markdown n'est pas +considérer comme un passage à la ligne, ça vous permet juste d'écrire des commentaires sans aller trop à droite dans votre IDE comme celui-ci. + +### Italic et gras + +```md +*Texte en italic* _Texte en italic_ + +**Texte en gras** __Texte en gras__ + +***Texte en italic et gras*** + +``` + + +### Titre et sous-titres + +```md +# Titre type h1 + +## Titre type h2 + +etc. jusqu'à + +###### Titre type h6 +``` + +### Listes + +```md +- Une +- Liste +- Non +- Ordonnée + +1. Une +2. Liste +3. Ordonnée + +- [x] Liste +- [ ] de +- [ ] tâches +``` + +#### Exemple + +- Une +- Liste +- Non +- Ordonnée + +1. Une +2. Liste +3. Ordonnée + +- [x] Liste +- [ ] de +- [ ] tâches + + +### Code + +```md + `Commentaire mono-ligne` +``` + +```md + ``` + Commentaire + Multi + ligne + ``` +``` + +```md + ```md + Commentaire + multi + ligne + avec + coloration + syntaxique (ici md pour markdown) + ``` +``` + +#### Exemple + + +Texte avant `Commentaire mono-ligne` texte après + +``` +Commentaire +multi +ligne +``` + +### Tableaux + +```md + +| Colonne 1 | Colonne 2 | +|-----------|-----------| +| ligne 1 | ligne 1 | +| ligne 2 | ligne 2 | + +``` + +#### Exemple + +| Colonne 1 | Colonne 2 | +|-----------|-----------| +| ligne 1 | ligne 1 | +| ligne 2 | ligne 2 | + +### Liens et images + +```md +[Mon lien](www.google.com) +![Mon image sur internet](www.imagelink.com/image.png) +![Mon image stocké sur mon pc](image/monscreenshot.png) +``` + + +## Faire des tests + +Pour écrire vos tests faites comme dans l'exemple ci-dessous: + +![Exemple de test](Screenshot_20221019_173551.png) + +Executez ensuite les tests en faisant `cargo test`, vous obtenez comme en suivant l'exemple ci-dessus le résultat de la figure 5. + +![Exemple de résultat des tests](Screenshot_20221019_174036.png) + +Lors d'un cargo build optimisé (`cargo build --release`), les tests ne sont pas inclus dans le fichier binaire. + +## Liens utiles + +La documentation officielle du crate core: [https://doc.rust-lang.org/core/index.html](https://doc.rust-lang.org/core/index.html) + +La documentation officielle du crate std: [https://doc.rust-lang.org/std/index.html](https://doc.rust-lang.org/std/index.html) + +La documentation des crates téléchargeable sur [https://crates.io/](https://crates.io/) est retrouvable sur: [https://docs.rs/](https://docs.rs/) + +Pour le markdown vous pouvez retrouver des tutos ici: [https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html) et ici [https://www.markdownguide.org/cheat-sheet/](https://www.markdownguide.org/cheat-sheet/) diff --git a/doc/Screenshot_20221019_153737.png b/doc/Screenshot_20221019_153737.png new file mode 100644 index 0000000..f407abb Binary files /dev/null and b/doc/Screenshot_20221019_153737.png differ diff --git a/doc/Screenshot_20221019_153803.png b/doc/Screenshot_20221019_153803.png new file mode 100644 index 0000000..8e7f3f7 Binary files /dev/null and b/doc/Screenshot_20221019_153803.png differ diff --git a/doc/Screenshot_20221019_153817.png b/doc/Screenshot_20221019_153817.png new file mode 100644 index 0000000..456a514 Binary files /dev/null and b/doc/Screenshot_20221019_153817.png differ diff --git a/doc/Screenshot_20221019_173551.png b/doc/Screenshot_20221019_173551.png new file mode 100644 index 0000000..463f662 Binary files /dev/null and b/doc/Screenshot_20221019_173551.png differ diff --git a/doc/Screenshot_20221019_174036.png b/doc/Screenshot_20221019_174036.png new file mode 100644 index 0000000..d404f4a Binary files /dev/null and b/doc/Screenshot_20221019_174036.png differ diff --git a/src/main.rs b/src/main.rs index e7a11a9..c38343f 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,18 @@ +#![warn(missing_docs)] + +//! # Crate burritos +//! +//! Crate du point d'entrée de burritos +//! +//! ## Liste des crate: +//! +//! - kernel +//! - machine +//! - A remplir + +/// Cette fonction est le point d'entrée de burritos +/// +/// Elle se contente de parser les arguments de lancement et les transmet ensuite fn main() { println!("Hello, world!"); }