dart-doc-validation

Je remarque que vous avez fourni "|-" ce qui semble être un début incomplet de tableau Markdown. Pouvez-vous s'il vous plaît fournir le texte complet à traduire ? Je suis prêt à : 1. Traduire le contenu en français 2. Préserver strictement le formatage Markdown 3. Conserver les noms propres, marques et commandes techniques en anglais 4. Retourner uniquement la traduction Veuillez partager le texte que vous souhaitez faire traduire.

npx skills add https://github.com/flutter/skills --skill dart-doc-validation

Validation de la 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 la présence de liens de documentation cassés, de références manquantes ou de macros incorrectes.
  • Vous préparez un package pour le publier 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

Validation de la Documentation en Local

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 souhaitez consulter la documentation générée en local, 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, par exemple python3 -m http.server.)

Correction des 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 dans 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 par le générateur de documentation.