Utiliser des exemples dans Dartdoc

Sommaire

• 1. La directive {@example}
• 2. Utiliser les régions
• 3. Masquer le code de configuration
• 4. Règles de filtrage des marqueurs
• 5. Placement et résolution des chemins
• 6. Vérification

Lors de la rédaction de documentation nécessitant des exemples de code multi-lignes, vous devez généralement extraire ces exemples dans des fichiers .dart autonomes et les injecter à l'aide de la directive {@example}, plutôt que de les écrire en ligne dans les commentaires ///. Cela garantit que les exemples peuvent être analysés, linté et exécutés.

1. La directive {@example}

La directive {@example} analyse un fichier externe et le résout en un bloc de code Markdown délimité dans la documentation générée.

Syntaxe : {@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}

• <path> : Le chemin du fichier. Un / initial s'évalue à partir de la racine du package. Sinon, il est relatif au fichier courant.
• lang : Le langage pour la clôture Markdown. Auto-détecté à partir de l'extension du fichier (par exemple, dart), mais peut être explicite (par exemple, lang=text).
• indent : strip (par défaut) supprime agressivement l'indentation commune du bloc de code.

Mauvais (Markdown inline) :

/// Makes a client service request to the backend.
///
/// ```dart
/// final client = Client();
/// client.send();
/// ```

Bon (Injection de fichier externe) :

/// Makes a client service request to the backend.
///
/// {@example /example/client_request.dart}

2. Utiliser les régions

Souvent, un fichier d'exemple externe contient des imports, de la configuration ou des wrappers void main() que vous ne voulez pas afficher dans la documentation. Vous pouvez extraire un bloc de code spécifique en ajoutant #<region> au chemin de la directive {@example}, et en encadrant ce code avec les commentaires #region et #endregion dans le fichier cible.

*Code Dart (par exemple, /example/client.dart) :

import 'package:http/http.dart';

void main() {
  // #region request_snippet
  final client = Client();
  client.send();
  // #endregion request_snippet
}

Utilisation dans Dartdoc :

/// Connects the client to the server and sends a request.
///
/// {@example /example/client.dart#request_snippet}

3. Masquer le code de configuration

S'il existe une ligne de code spécifique dans votre région extraite qui est nécessaire pour que le compilateur/analyseur passe mais qui est hors de propos (ou distrayante) pour le lecteur de la documentation, ajoutez #hide à cette ligne.

Code Dart :

final mockServer = startServer(); // #hide
final data = await fetch(mockServer.url);

Dans la documentation générée, seul final data = await fetch(mockServer.url); sera visible. La ligne avec #hide est complètement supprimée.

4. Règles de filtrage des marqueurs

Lorsque vous travaillez avec les marqueurs #hide, #region et #endregion, vous devez respecter ces deux contraintes techniques :

• Région requise : Les marqueurs ne sont traités et supprimés que lorsque vous ciblez un suffixe de région spécifique (par exemple, {@example file.dart#region_name}). Si vous injectez un fichier entier sans suffixe de région, le fichier est intégré exactement comme il apparaît dans la source, y compris tout texte de marqueur comme // #hide.
• Agnosticisme de format : Le système de marqueurs est complètement agnostique quant au format. Dartdoc exécute simplement une regex pour supprimer les lignes contenant les chaînes de marqueurs, ce qui signifie qu'il fonctionne de manière identique dans les fichiers autres que Dart (par exemple, à l'intérieur de commentaires YAML # #region ou de commentaires HTML <!-- #region -->).

5. Placement et résolution des chemins

La directive {@example} est une directive au niveau du bloc. Elle doit apparaître sur sa propre ligne préfixée par ///. Son analyseur <path> interne suit des règles de référence URI strictes :

• Chemins racine du package (/) : Les chemins commençant par une barre oblique se résolvent automatiquement directement à la racine du package Dart. Utilisez ceci lorsque le fichier de destination est profond.
  • Exemple : {@example /test/data/sample.txt} correspond exactement à <package_root>/test/data/sample.txt.
• Chemins relatifs : Les chemins sans barre oblique initiale se résolvent relatif au répertoire du fichier contenant le commentaire de documentation.
  • Exemple : {@example ../utils/demo.dart}
• Application des limites : L'utilisation de segments .. pour traverser vers le haut est parfaitement acceptable, mais dartdoc arrête nativement la traversée de répertoires à la racine du package (il ne s'échappera jamais du package).
• Pas d'URL réseau : Les URI absolus (par exemple, commençant par https://) ne sont strictement pas supportés. Le fichier d'exemple doit se trouver nativement quelque part dans le système de fichiers local.
• Séparateurs et encodage : Parce que dartdoc résout le chemin comme un URI, vous devez toujours utiliser des barres obliques (/) comme séparateurs de dossiers (même sous Windows). Vous pouvez nativement inclure des caractères codés en URI (comme %20 pour les espaces) comme autorisé par les règles de référence URI.

6. Vérification

Après injection d'exemples :

1. Exécutez dart analyze sur les fichiers d'exemple pour vérifier que le code de configuration masqué compile.
2. (Optionnel) Exécutez dart doc pour vérifier que dartdoc a correctement analysé la directive sans lever d'avertissement "Failed to read file" ou "missing region".