Rédiger la documentation API Dart

Sommaire

• 1. Champ d'application et structure
• 2. Ton et formules d'ouverture
• 3. Anti-motifs stricts (interdits)
• 4. Placement technique et résolution
• 5. Liens et Markdown
• 6. Vérification
• Exemples

Lorsque vous êtes invité à rédiger ou mettre à jour la documentation du code Dart, vous devez respecter strictement ces règles de formatage basées sur les directives « Effective Dart: Documentation ».

1. Champ d'application et structure

• API publiques ciblées : Concentrez vos efforts de documentation sur les déclarations publiques. Ne documentez pas les membres privés (ceux commençant par un tiret bas _) sauf indication explicite, car ils n'apparaissent pas sur les sites de référence API générés.
• Toujours utiliser /// : Utilisez des commentaires en ligne /// consécutifs pour toute la documentation API. N'utilisez jamais les commentaires en bloc /** ... */.
• Phrases appropriées : Formatez tous les commentaires comme des phrases appropriées. Commencez par une majuscule (sauf s'il s'agit d'un identifiant minuscule) et terminez par un point.
• Le premier paragraphe : Le premier paragraphe d'un commentaire de documentation doit être une seule phrase concise qui résume l'élément. Terminez-le avec un point. Dartdoc l'extrait tel quel pour les vues de liste.
• Séparation : Séparez toujours le résumé de la première phrase du reste de la documentation avec une ligne vide contenant ///. Ne produisez jamais une newline complètement vide (par exemple, un \n sans ///), car cela termine le bloc de commentaire de documentation.

2. Ton et formules d'ouverture

• Groupes nominaux pour les propriétés : Commencez les descriptions des variables, getters ou setters par un groupe nominal. /// Le rayon de la sphère. (Non « Obtient le rayon... »)
• « Whether » pour les booléens : Commencez la documentation des propriétés booléennes par « Whether ». /// Whether the connection is active.
• Verbes à la troisième personne pour les méthodes : Commencez les descriptions des méthodes ou fonctions par un verbe à la troisième personne qui décrit ce qu'elles font. /// Initializes the database. (Non « Initialize » ou « This method initializes »)
• Éviter la redondance : Ne réénoncez pas la signature ou le nom de l'élément. Ne dites pas « This class is a... » ou « The foo method does... ».

3. Anti-motifs stricts (interdits)

• Pas de balises Javadoc/TSDoc (@param, @return, @throws, etc.) : N'utilisez jamais les balises de style Javadoc (@param, @return, @returns, @throws, @exception, @see, @type). Intégrez plutôt les noms de paramètres, le comportement de retour et les exceptions dans le texte.

4. Placement technique et résolution

• Annotations (@override, etc.) : Les commentaires de documentation doivent être placés avant les annotations de métadonnées.
• Documentation héritée : Évitez de dupliquer les commentaires de documentation sur les membres @override si le comportement ne diffère pas de la superclasse ou de l'interface. Dartdoc hérite automatiquement de la documentation de base.
• Paires getter/setter : Si une propriété possède à la fois un getter et un setter, placez la documentation uniquement sur le getter. L'outillage émettra un avertissement si les deux sont documentés.
• Constructeurs par défaut : Pour créer un lien vers un constructeur par défaut sans nom dans les commentaires de documentation, vous devez utiliser la syntaxe .new (par exemple, [ClassName.new]).

5. Liens et Markdown

• Crochets ([identifier]) pour les symboles en champ : Utilisez des crochets pour créer un lien vers n'importe quel identifiant en champ (paramètres, classes, méthodes, champs et fonctions de haut niveau) afin que dartdoc puisse les résoudre. N'utilisez jamais les accents graves pour les paramètres.
• Pas de parenthèses dans les liens de méthodes : Évitez les parenthèses dans les liens (par exemple, utilisez [String.contains], pas [String.contains()]).
• Accents graves pour les mots-clés et littéraux : Utilisez les accents graves pour les mots-clés, littéraux et expressions arbitraires (par exemple `null`, `true`, `void`). Ne placez jamais les mots-clés entre crochets (évitez [null] ou [true]).
• Liens hors champ : Si vous devez créer un lien vers un symbole qui n'est pas importé par la bibliothèque actuelle, utilisez la directive @docImport en haut du fichier (sur la déclaration library;) plutôt que d'ajouter un import standard.
• Blocs de code : Pour les exemples de code, étiquetez toujours la clôture de langage. Utilisez ```dart pour Dart ou ```sh pour les commandes shell. Ne laissez pas les blocs de code sans étiquette, car Dartdoc tentera de détecter automatiquement le langage et se trompe fréquemment.
• Formatage : Utilisez le Markdown standard (gras, listes, etc.) après le premier paragraphe pour expliquer complètement les cas limites, les exceptions levées et le comportement interne que l'appelant ne peut pas voir.

6. Vérification

Après avoir écrit ou mis à jour des commentaires de documentation :

1. Exécutez dart analyze pour vous assurer que toutes les références entre crochets se résolvent correctement sans déclencher d'avertissements comment_references.
2. (Optionnel) Exécutez dart doc pour vérifier que la documentation générée s'affiche correctement.

Exemples

1. Balises interdites ou prose

Mauvais :

/// This method fetches data.
/// @param force true to force reload.
/// @return the data
/// @throws NetworkException if host is unreachable.
Data load(bool force) { ... }

Bon :

/// Fetches the remote data.
///
/// If [force] is true, this bypasses the local cache and forces a
/// network request.
///
/// Throws a [NetworkException] if the host is unreachable.
Data load(bool force) { ... }

2. Le piège du placement des annotations

Mauvais :

@override
/// Renders the widget to the screen.
Widget build(BuildContext context) { ... }

Bon :

/// Renders the widget to the screen.
@override
Widget build(BuildContext context) { ... }

3. Formules d'ouverture et ton

Mauvais :

/// Gets if the connection is active.
bool get isActive => _active;

/// This method initializes the connection.
void init() { ... }

Bon :

/// Whether the connection is active.
bool get isActive => _active;

/// Initializes the connection.
void init() { ... }

4. Lien vers un constructeur

Mauvais :

/// Creates a new user. Similar to calling [User()].
User.create() { ... }

Bon :

/// Creates a new user. Similar to calling [User.new].
User.create() { ... }

5. Liens hors champ (@docImport)

Mauvais :

import 'package:http/http.dart'; // Adds unnecessary runtime dependency just for docs

/// To use this, you must pass a [Client].

Bon :

/// @docImport 'package:http/http.dart';
library;

/// To use this, you must pass a [Client].