Initial commit
This commit is contained in:
Zhongwei Li
202
commands/update-dart-doc.md
Normal file
202
commands/update-dart-doc.md
Normal file
@@ -0,0 +1,202 @@
|
||||
## 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
|
||||
Reference in New Issue
Block a user