203 lines
6.9 KiB
Markdown
203 lines
6.9 KiB
Markdown
## Update Dart Doc
|
|
|
|
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
|