Update Dart Doc

---
description: "Gérer systématiquement les commentaires DartDoc. Se déclenche avec « mettre à jour DartDoc »."
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
---

# 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

```bash
# 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

```bash
# 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** :

```dart
/// {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)** :

```dart
/// É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** :

```dart
/// 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

```bash
# 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** :

```bash
# 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