Merge branch 'doc' into 'main'

Ajout explication d'utilisation de la doc et autres choses

Closes #5

See merge request simpleos/burritos!1
This commit is contained in:
François Autin 2022-10-19 16:56:17 +00:00
commit 3086d22b35
8 changed files with 218 additions and 0 deletions

7
Cargo.lock generated Normal file
View File

@ -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"

196
doc/DOCUMENTATION.md Normal file
View File

@ -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/)

Binary file not shown.

After

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 54 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 42 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 66 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

View File

@ -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!");
}