Validation de documentation Dart

1. Quand utiliser cette compétence

Utilisez cette compétence quand :

• Vous écrivez ou mettez à jour des commentaires de documentation (///) dans du code Dart.
• Vous vérifiez des liens de documentation cassés, des références ou des macros.
• Vous préparez un package pour la publication sur pub.dev.

Discovery

Pour trouver les problèmes de documentation :

Lint manquant

Vérifiez si le lint comment_references est activé :

• Cible : analysis_options.yaml
• Requête de recherche : comment_references

Validation automatisée

Exécutez le générateur de documentation pour identifier les avertissements :

• Commande : dart doc -o $(mktemp -d)
• Mots-clés à rechercher : warning:, unresolved doc reference, undefined macro

2. Bonnes pratiques

Activez le lint de validation de documentation

Dans votre analysis_options.yaml, activez le lint comment_references.

linter:
  rules:
    - comment_references

Valider la documentation localement

Utilisez la commande dart doc avec un répertoire de sortie temporaire pour valider les commentaires de documentation sans polluer l'espace de travail du projet local.

Cette commande analyse tous les commentaires de documentation et signale des avertissements tels que :

• warning: unresolved doc reference
• warning: undefined macro

Commande à exécuter :

dart doc -o $(mktemp -d)

Cela fonctionne sur Mac et Linux.

Cela garantit que les fichiers HTML générés sont stockés dans un emplacement temporaire et n'encombrent pas le répertoire du package, tout en signalant tous les avertissements de validation dans la sortie du terminal.

Parcourir la documentation :

Notre documentation utilise des fonctionnalités conçues pour s'exécuter sur un serveur web. Si vous voulez parcourir la documentation générée localement, installez le package dhttpd.

pub global activate dhttpd
TMP_DIR=$(mktemp -d) && dart doc -o "$TMP_DIR" &&  dhttpd --path "$TMP_DIR"

(Ou utilisez un autre serveur HTTP, comme python3 -m http.server.)

Corriger les avertissements courants

• Référence de documentation non résolue : Assurez-vous que tout identifiant entre crochets ([Identifier]) pointe correctement vers une classe, une méthode, une propriété ou un paramètre existant dans la portée actuelle ou les bibliothèques importées.
• Macro non définie : Si vous utilisez {@macro macro_name}, assurez-vous que le modèle {@template macro_name} est défini dans le même fichier ou dans un fichier qui est importé et visible pour le générateur de documentation.