BurritOS/doc/DOCUMENTATION.md

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