4.0 KiB
Comment utiliser la documentation Rust
Écrire un commentaire en Rust
Pour écrire un commentaire qui apparaitra sur la doc de cargo, écrivez :
/// Votre commentaire
pour commenter votre fonction, attribut, structure....
Pour les commentaires de crate et module, utilisez :
//! 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.
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 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
*Texte en italic* _Texte en italic_
**Texte en gras** __Texte en gras__
***Texte en italic et gras***
Titre et sous-titres
# Titre type h1
## Titre type h2
etc. jusqu'à
###### Titre type h6
Listes
- Une
- Liste
- Non
- Ordonnée
1. Une
2. Liste
3. Ordonnée
- [x] Liste
- [ ] de
- [ ] tâches
Exemple
- Une
- Liste
- Non
- Ordonnée
- Une
- Liste
- Ordonnée
- Liste
- de
- tâches
Code
`Commentaire mono-ligne`
```
Commentaire
Multi
ligne
```
```md
Commentaire
multi
ligne
avec
coloration
syntaxique (ici md pour markdown)
```
Exemple
Texte avant Commentaire mono-ligne texte après
Commentaire
multi
ligne
Tableaux
| 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
[Mon lien](www.google.com)
Autres
Vous pouvez retrouver d'autres exemples par ici:
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
ou ici
https://www.markdownguide.org/cheat-sheet/ -- Méga utile
Liens utiles
La documentation officielle du crate core: https://doc.rust-lang.org/core/index.html
La documentation officielle du crate std: https://doc.rust-lang.org/std/index.html
La documentation des crates téléchargeable sur https://crates.io/ est retrouvable sur: https://docs.rs/