From e6f190e035f2bd73e30bd928cd0c70da2de97eb3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Bousqui=C3=A9?=
 <jerome.bousquie@ut-capitole.fr>
Date: Wed, 16 Sep 2026 09:45:33 +0200
Subject: [PATCH] docs: add API documentation guidelines (rustdoc) in
 docs/DOCUMENTATION.md

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.
---
 docs/DOCUMENTATION.md | 80 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/DOCUMENTATION.md

diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md
new file mode 100644
index 0000000..90f60cf
--- /dev/null
+++ b/docs/DOCUMENTATION.md
@@ -0,0 +1,80 @@
+---
+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 ``` ` |