Jérôme Bousquié
e6f190e035
Codifies the systematic documentation of public items with the API docs in mind, based on the incidents from the last session: backticks around every type (Option<Self>, Arc<Mesh>, [f32; 3]) to avoid unresolved-link and unclosed-HTML-tag warnings, one doc comment per public item, the #![warn(missing_docs)] policy, verifying '0 warnings' via cargo doc before committing, and doc-test conventions (rust vs ignore blocks). Applies to wsg-lib development from now on.
81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
---
|
|
type: Rule
|
|
title: Guidelines for API Documentation (rustdoc)
|
|
description: Consignes pour documenter systématiquement le code en pensant à la génération de documentation d'API (rustdoc) dans le projet WSG
|
|
tags: [documentation, rustdoc, api, guidelines, wsg-lib]
|
|
status: active
|
|
stale_after: 2027-01-31T00:00:00Z
|
|
related: [docs/rules/DOCUMENTATION.md]
|
|
generated: { by: "human:jerome", at: 2026-09-16T00:00:00Z }
|
|
---
|
|
|
|
# Consignes de Documentation d'API (rustdoc)
|
|
|
|
Ce document complète `docs/rules/DOCUMENTATION.md` (règles générales, en anglais). Il définit la
|
|
manière **concrète** d'écrire les commentaires pour que `cargo doc` produise une documentation d'API
|
|
de qualité, **sans aucun avertissement**. Ces consignes s'appliquent à toute modification de code du
|
|
projet, y compris la doc elle-même.
|
|
|
|
## Principe
|
|
|
|
Chaque item public (`pub struct`, `pub enum`, `pub trait`, `pub fn`, `pub const`, module, crate)
|
|
est documenté **au moment où il est écrit**, pas après coup. On ne documente pas seulement *ce que*
|
|
fait le code, mais *pourquoi* il existe et *quand/par qui* il est appelé (cf. règles générales :
|
|
description ≤ 3 lignes, étapes internes ≤ 3 lignes si corps > 15 lignes, points techniques ≤ 3 lignes).
|
|
|
|
## Règles techniques (issues d'incidents réels)
|
|
|
|
### 1. Types et code entre backticks
|
|
|
|
Tout nom de type, fonction, variable ou fragment de code dans un commentaire est enveloppé de
|
|
backticks (`` ` ``). Sans cela, rustdoc croit :
|
|
|
|
- à un **lien intra-doc** pour tout ce qui est entre crochets → avertissement `unresolved link`
|
|
(ex. `[f32; 3]` au lieu de `` `[f32; 3]` ``) ;
|
|
- à une **balise HTML** pour tout `<X>` → avertissement `unclosed HTML tag`
|
|
(ex. `Option<Self>`, `Arc<Mesh>`, `Handle<T>` au lieu de `` `Option<Self>` ``…).
|
|
|
|
À proscrire : `Option<Self>`, `Vec<Mesh>`, `[f32; 3]`, `Arc<Material>`.
|
|
À écrire : `` `Option<Self>` ``, `` `Vec<Mesh>` ``, `` `[f32; 3]` ``, `` `Arc<Material>` ``.
|
|
|
|
### 2. Un commentaire par item public
|
|
|
|
- Crate / module : `//!` en tête de fichier.
|
|
- Item (struct, enum, trait, fn, const, champs) : `///` juste au-dessus.
|
|
- Toute structure publique dont seuls les champs sont commentés déclenche `missing_docs` :
|
|
commenter **aussi** la structure elle-même.
|
|
|
|
### 3. Faire remonter les trous de couverture
|
|
|
|
`#![warn(missing_docs)]` est actif en tête de `lib.rs`. Tout nouvelle item public sans doc remonte
|
|
en **warning** au build de la doc : c'est voulu, il faut le corriger avant de committer.
|
|
Un rendu de doc doit toujours terminer par « generated 0 warnings ».
|
|
|
|
### 4. Vérifier le rendu avant de committer
|
|
|
|
Après toute modification de doc :
|
|
|
|
```bash
|
|
cargo doc -p wsg-lib --no-deps # doit afficher « generated 0 warnings »
|
|
cargo doc --no-deps --open # ouvre la doc dans le navigateur
|
|
cargo check --workspace # compile sans erreur
|
|
```
|
|
|
|
### 5. Tests de documentation
|
|
|
|
- Un bloc de code ```rust``` dans un commentaire est compilé et exécuté par `cargo test` (doc-test) :
|
|
il doit compiler **et** tourner.
|
|
- Pour un extrait non autonome (dépend de winit/wgpu, etc.), utiliser ` ```ignore ```` ```` au lieu de
|
|
` ```rust ``` ` afin de ne pas casser `cargo test`.
|
|
|
|
## Récapitulatif
|
|
|
|
| Situation | À faire | À éviter |
|
|
|---|---|---|
|
|
| Type dans une doc | `` `Arc<Mesh>` `` | `Arc<Mesh>` |
|
|
| Tableau dans une doc | `` `[f32; 3]` `` | `[f32; 3]` |
|
|
| Item public sans description | ajouter `///` | laisser vide |
|
|
| Struct publique | doc sur la struct + les champs | doc sur les champs seuls |
|
|
| Extraits exécutables | ` ```rust ``` ` | ` ```ignore ``` ` |
|
|
| Extraits non autonomes | ` ```ignore ``` ` | ` ```rust ``` ` |
|