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