wsg/docs/DOCUMENTATION.md

type, title, description, tags, status, stale_after, related, generated

type	title	description	tags	status	stale_after	related	generated
Rule	Guidelines for API Documentation (rustdoc)	Consignes pour documenter systématiquement le code en pensant à la génération de documentation d'API (rustdoc) dans le projet WSG	documentation rustdoc api guidelines wsg-lib	active	2027-01-31T00:00:00Z	docs/rules/DOCUMENTATION.md	by at human:jerome 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 :

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 cassercargo 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 ```