197 lines
4.5 KiB
Markdown
197 lines
4.5 KiB
Markdown
# Comment utiliser la documentation Rust
|
|
|
|
|
|
|
|
## É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.
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 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)
|
|
|
|
|
|
```
|
|
|
|
|
|
## Faire des tests
|
|
|
|
Pour écrire vos tests faites comme dans l'exemple ci-dessous:
|
|
|
|
|
|
|
|
Executez ensuite les tests en faisant `cargo test`, vous obtenez comme en suivant l'exemple ci-dessus le résultat de la figure 5.
|
|
|
|
|
|
|
|
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/)
|