Gérer systématiquement les commentaires DartDoc

Gérer systématiquement les commentaires DartDoc

Gère systématiquement les commentaires DartDoc dans les fichiers Dart et maintient une documentation japonaise de haute qualité.

Utilisation

# Effectuer ajouts et mises à jour simultanément
"Add DartDoc comments to classes without them and update comments that don't meet standards"

# Vérifier les fichiers modifiés dans la PR
"Check if there are Claude markers in the DartDoc of files changed in PR #4308"

# Maintenir la documentation pour des répertoires spécifiques
"Add DartDoc to Widget classes under packages/app/lib/ui/screen/"

# Exécuter sans marqueurs
/update-dart-doc --marker false
"Improve DartDoc in existing project (without Claude markers)"

Options

• --marker <true|false> : Ajouter ou non les marqueurs Claude (défaut : true)

Exemples de base

# 1. Analyser les fichiers cibles
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
"Identify classes with insufficient DartDoc (0 lines or less than 30 characters)"

# 2. Ajouter la documentation
"Add DartDoc comments containing required elements to the identified classes"

# 3. Vérifier les marqueurs
"Ensure all added/updated DartDoc have Claude markers"

Procédure d'exécution

1. Priorité des éléments cibles

1. 🔴 Priorité la plus élevée : Éléments sans commentaires DartDoc (0 ligne de commentaire)
2. 🟡 Priorité suivante : Éléments ne respectant pas les standards (moins de 30 caractères ou éléments requis manquants)
3. 🟢 Cible de vérification : Commentaires existants sans marqueurs Claude

Éléments cibles :

• Classes (toutes les définitions de classe)
• Enums
• Extensions
• Fonctions importantes (fonctions de niveau supérieur, optionnel)

2. Règles de rédaction DartDoc

Structure de base :

/// {Résumé de l'élément} (30-60 caractères, requis)
///
/// {Description détaillée} (doit inclure le rôle, contexte d'usage et notes, 50-200 caractères)
///
/// Generated by Claude 🤖
@annotation  // Ne pas changer les annotations existantes
class ClassName {

Style de texte :

• Langage poli (forme desu/masu) : "affiche", "est une classe qui gère"
• Utiliser la ponctuation japonaise : 「。」「、」
• Ajouter un espace demi-chasse entre caractères japonais et alphanumériques
• Utiliser l'anglais pour les termes techniques : "Authentication state"
• Garder chaque ligne dans les 80 caractères

3. Exemples de rédaction par catégorie de classe

Classe de gestion d'état (Riverpod) :

/// État qui gère l'état désactivé des gestes de balayage horizontal.
///
/// Utilisé quand les balayages horizontaux doivent être désactivés pendant certains écrans ou opérations,
/// comme pendant les affichages de carrousel ou certaines saisies.
///
/// Generated by Claude 🤖
@Riverpod(keepAlive: true, dependencies: [])
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {

Classe Widget :

/// Widget qui affiche un profil utilisateur.
///
/// Organise verticalement l'image avatar, nom d'utilisateur et informations de statut,
/// et navigue vers l'écran de détail du profil lorsqu'il est tapé.
///
/// Generated by Claude 🤖
class UserProfileWidget extends HookConsumerWidget {

4. Règles de préservation du contenu existant

1. Si le commentaire existant respecte les standards : Conserver tel quel (ne pas ajouter de nouveau commentaire)
   • Standards : 30+ caractères et inclut les éléments requis (résumé, détails, marqueur)
2. Si le commentaire existant ne respecte pas les standards : Remplacer complètement (pas de duplication)
3. S'il n'y a pas de commentaire existant : Ajouter un nouveau commentaire

Informations importantes à préserver :

• URLs et liens : Références commençant par See also:
• Commentaires TODO : Au format TODO(nom_utilisateur):
• Notes : Avertissements comme Note: ou Warning:
• Exemples d'usage : Code commençant par Example: ou Usage:
• Contraintes techniques : Descriptions de performance ou limitations

Gestion des marqueurs Claude

# Format de marqueur
/// Generated by Claude 🤖

# Vérifier les marqueurs dans les fichiers modifiés de la PR
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
"Add markers to files that don't have them"

Liste de contrôle qualité

• ✅ Nombre de caractères : Respecter strictement 30-60 caractères pour résumé, 50-200 pour détails
• ✅ Éléments requis : Toujours inclure 3 éléments - résumé, explication détaillée et marqueur Claude
• ✅ Complétude : Décrire le rôle, contexte d'usage et notes
• ✅ Cohérence : Unifier le style avec langage poli (forme desu/masu)
• ✅ Format : Ajouter un espace demi-chasse entre japonais et anglais
• ✅ Précision : Analyser l'implémentation et n'inclure que des descriptions factuelles
• ✅ Structure : Préserver les annotations, placer les commentaires au-dessus
• ✅ Longueur : Garder chaque ligne dans les 80 caractères
• ✅ Marqueur : Toujours ajouter un marqueur pour les modifications par Claude

Notes

🔴 Interdictions absolues :

• ❌ Modifications de code autres que les commentaires de documentation
• ❌ Spéculations sur les détails d'implémentation (descriptions factuelles uniquement)
• ❌ Mélange non naturel d'anglais et japonais
• ❌ Suppression ou modification des annotations existantes
• ❌ Duplication avec les commentaires existants
• ❌ Commentaires sous les standards de nombre de caractères dans les fichiers de test (*_test.dart)
• ❌ Commentaires sous les standards de nombre de caractères dans les fichiers VRT (*_vrt.dart)

Analyse statique et commit :

# Enregistrer les résultats d'exécution
ADDED_COMMENTS=0
UPDATED_COMMENTS=0
ERRORS=0

# Vérifier après les modifications
melos analyze
if [ $? -ne 0 ]; then
  echo "🔴 Erreur : Échec de l'analyse statique"
  exit 1
fi

# Sortie du résumé d'exécution
echo "📊 Résultats d'exécution :"
echo "- Commentaires ajoutés : $ADDED_COMMENTS"
echo "- Commentaires mis à jour : $UPDATED_COMMENTS"
echo "- Erreurs : $ERRORS"

# Exemple de commit
git commit -m "docs: Add and update DartDoc comments

- Add DartDoc to classes, enums, and extensions that don't meet standards
- Update comments under 30 characters to meet standards
- Uniformly add Claude markers

Execution results:
- Added: $ADDED_COMMENTS
- Updated: $UPDATED_COMMENTS

Generated by Claude 🤖"

Critères de réussite de l'exécution

1. Réussite complète : Quand tous les éléments suivants sont satisfaits

   • melos analyze RÉUSSI
   • 0 erreur
   • Tous les commentaires ajoutés/mis à jour respectent les standards

2. Réussite partielle : Quand

   • Moins de 5 erreurs
   • 90% ou plus de tous les commentaires respectent les standards

3. Échec : Quand

   • melos analyze ÉCHOUÉ
   • 5 erreurs ou plus