Initial commit
This commit is contained in:
Zhongwei Li
306
commands/update-doc-string.md
Normal file
306
commands/update-doc-string.md
Normal file
@@ -0,0 +1,306 @@
|
||||
## Update Doc String
|
||||
|
||||
Gère systématiquement les docstrings/commentaires multilingues et maintient une documentation de haute qualité.
|
||||
|
||||
### Utilisation
|
||||
|
||||
```bash
|
||||
# Exécuter avec détection automatique de langue
|
||||
"Please add docstrings to classes and functions without them, and update comments that don't meet standards"
|
||||
|
||||
# Exécuter avec langue spécifiée
|
||||
/update-doc-string --lang python
|
||||
"Please update docstrings in Python files to comply with PEP 257"
|
||||
|
||||
# Maintenir la documentation pour des répertoires spécifiques
|
||||
"Please add JSDoc to functions under src/components/"
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
- `--lang <en|fr>` : Langue de documentation (défaut : détection automatique depuis les commentaires existants, sinon en)
|
||||
- `--style <style>` : Spécifier le style de documentation (a des défauts spécifiques à la langue)
|
||||
- `--marker <true|false>` : Ajouter ou non les marqueurs Claude (défaut : true)
|
||||
|
||||
### Exemples de base
|
||||
|
||||
```bash
|
||||
# 1. Analyser les fichiers cibles (langage de programmation détecté automatiquement)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
|
||||
"Please identify elements with insufficient docstrings (0 comment lines or fewer than 30 characters)"
|
||||
|
||||
# 2. Ajouter la documentation (utilise l'anglais par défaut)
|
||||
"Please add docstrings containing language-specific required elements to the identified elements"
|
||||
# → Utilise l'anglais pour toute la documentation
|
||||
|
||||
# 3. Ajouter la documentation (spécifier explicitement l'anglais)
|
||||
/update-doc-string --lang en
|
||||
"Add docstrings with required elements to the identified elements"
|
||||
|
||||
# 4. Vérifier les marqueurs
|
||||
"Please confirm that all added/updated docstrings have Claude markers"
|
||||
```
|
||||
|
||||
### Étapes d'exécution
|
||||
|
||||
#### 1. Priorité des éléments cibles
|
||||
|
||||
1. 🔴 **Priorité la plus élevée** : Éléments sans docstrings/commentaires (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 (communs à tous langages)** :
|
||||
|
||||
- Définitions de classe
|
||||
- Fonctions/méthodes
|
||||
- Modules (Python, Go)
|
||||
- Enums
|
||||
- Interfaces (TypeScript, Go)
|
||||
|
||||
#### 2. Règles de documentation spécifiques aux langages
|
||||
|
||||
**Python (PEP 257)** :
|
||||
|
||||
```python
|
||||
# Version anglaise (défaut)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""Calculate the total amount for a list of items. (30-60 characters)
|
||||
|
||||
Multiplies the price and quantity of each item and returns
|
||||
the total with tax. Returns 0.0 for empty lists. (50-200 characters)
|
||||
|
||||
Args:
|
||||
items: List of items to calculate
|
||||
|
||||
Returns:
|
||||
Total amount with tax
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
|
||||
# Version anglaise (--lang en)
|
||||
def calculate_total(items: List[Item]) -> float:
|
||||
"""Calculate the total amount for a list of items. (30-60 chars)
|
||||
|
||||
Multiplies the price and quantity of each item and returns
|
||||
the total with tax. Returns 0.0 for empty lists. (50-200 chars)
|
||||
|
||||
Args:
|
||||
items: List of items to calculate
|
||||
|
||||
Returns:
|
||||
Total amount with tax
|
||||
|
||||
Generated by Claude 🤖
|
||||
"""
|
||||
```
|
||||
|
||||
**JavaScript/TypeScript (JSDoc)** :
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Component that displays a user profile. (30-60 characters)
|
||||
*
|
||||
* Displays avatar image, username, and status information,
|
||||
* and navigates to the profile detail screen when clicked. (50-200 characters)
|
||||
*
|
||||
* @param {Object} props - Component properties
|
||||
* @param {string} props.userId - User ID
|
||||
* @param {boolean} [props.showStatus=true] - Status display flag
|
||||
* @returns {JSX.Element} Rendered component
|
||||
*
|
||||
* @generated by Claude 🤖
|
||||
*/
|
||||
const UserProfile = ({ userId, showStatus = true }) => {
|
||||
```
|
||||
|
||||
**Go** :
|
||||
|
||||
```go
|
||||
// CalculateTotal calculates the total amount for a list of items. (30-60 characters)
|
||||
//
|
||||
// Multiplies the price and quantity of each item and returns
|
||||
// the total with tax. Returns 0.0 for empty slices. (50-200 characters)
|
||||
//
|
||||
// Generated by Claude 🤖
|
||||
func CalculateTotal(items []Item) float64 {
|
||||
```
|
||||
|
||||
**Rust** :
|
||||
|
||||
```rust
|
||||
/// Calculate the total amount for a list of items. (30-60 characters)
|
||||
///
|
||||
/// Multiplies the price and quantity of each item and returns
|
||||
/// the total with tax. Returns 0.0 for empty vectors. (50-200 characters)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
pub fn calculate_total(items: &[Item]) -> f64 {
|
||||
```
|
||||
|
||||
**Dart (DartDoc)** :
|
||||
|
||||
```dart
|
||||
/// Widget that displays a user profile. (30-60 characters)
|
||||
///
|
||||
/// Vertically arranges avatar image, username, and status information,
|
||||
/// and navigates to the profile detail screen when tapped. (50-200 characters)
|
||||
///
|
||||
/// Generated by Claude 🤖
|
||||
class UserProfileWidget extends StatelessWidget {
|
||||
```
|
||||
|
||||
#### 3. Règles de rétention du contenu existant
|
||||
|
||||
1. **Si les commentaires existants respectent les standards** : Garder tels quels (ne pas en ajouter de nouveaux)
|
||||
- Standards : Au moins 30 caractères et inclut les éléments requis (résumé, détails, marqueur)
|
||||
2. **Si les commentaires existants ne respectent pas les standards** : Remplacer complètement (pas de duplication)
|
||||
3. **S'il n'y a pas de commentaires existants** : Ajouter de nouveaux commentaires
|
||||
|
||||
**Informations importantes à retenir** :
|
||||
|
||||
- URLs et liens : `See also:`, `@see`, `References:` etc.
|
||||
- Commentaires TODO : Format `TODO:`, `FIXME:`, `XXX:`
|
||||
- Notes : `Note:`, `Warning:`, `Important:` etc.
|
||||
- Exemples : `Example:`, `Usage:`, `# Examples` etc.
|
||||
- Descriptions existantes de paramètres et valeurs de retour
|
||||
|
||||
### Paramètres spécifiques aux langages
|
||||
|
||||
```yaml
|
||||
# Paramètres par défaut spécifiques aux langages
|
||||
languages:
|
||||
python:
|
||||
style: "google" # google, numpy, sphinx
|
||||
indent: 4
|
||||
quotes: '"""
|
||||
|
||||
javascript:
|
||||
style: "jsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
typescript:
|
||||
style: "tsdoc"
|
||||
indent: 2
|
||||
prefix: "/**"
|
||||
suffix: "*/"
|
||||
|
||||
go:
|
||||
style: "godoc"
|
||||
indent: 0
|
||||
prefix: "//"
|
||||
|
||||
rust:
|
||||
style: "rustdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
|
||||
dart:
|
||||
style: "dartdoc"
|
||||
indent: 0
|
||||
prefix: "///"
|
||||
```
|
||||
|
||||
### 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 résumé, description détaillée et marqueur Claude
|
||||
- ✅ **Complétude** : Décrire rôle, contexte d'usage et notes
|
||||
- ✅ **Conventions linguistiques** : Respecter les guides de style officiels pour chaque langue
|
||||
- ✅ **Exceptions** : Expliquer erreurs et exceptions (quand applicable)
|
||||
- ✅ **Précision** : Analyser l'implémentation et n'inclure que des descriptions factuelles
|
||||
|
||||
### Notes
|
||||
|
||||
**🔴 Interdictions strictes** :
|
||||
|
||||
- ❌ Modifications de code autres que les commentaires de documentation
|
||||
- ❌ Spéculations sur les détails d'implémentation (faits uniquement)
|
||||
- ❌ Formats violant les conventions linguistiques
|
||||
- ❌ Suppression ou modification des annotations de type existantes
|
||||
- ❌ Duplication avec les commentaires existants
|
||||
- ❌ Commentaires sous les standards de nombre de caractères dans les fichiers de test
|
||||
|
||||
**Exécution et vérification** :
|
||||
|
||||
```bash
|
||||
# Enregistrer les résultats d'exécution
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# Détection automatique de langue à partir des commentaires existants
|
||||
# Si des caractères français (accents, cédilles) sont détectés, utiliser fr ; sinon, utiliser en
|
||||
DOC_LANGUAGE="en" # Défaut
|
||||
if grep -E -r '[àâäáãåæçèéêëìíîïñòóôöõøùúûüÿýßÀÂÄÁÃÅÆÇÈÉÊËÌÍÎÏÑÒÓÔÖÕØÙÚÛÜŸÝ]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
|
||||
DOC_LANGUAGE="fr"
|
||||
fi
|
||||
|
||||
# Détection automatique du langage de programmation et analyse statique
|
||||
if [ -f "*.py" ]; then
|
||||
pylint --disable=all --enable=missing-docstring .
|
||||
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
|
||||
eslint . --rule 'jsdoc/require-jsdoc: error'
|
||||
elif [ -f "*.go" ]; then
|
||||
golint ./...
|
||||
elif [ -f "*.rs" ]; then
|
||||
cargo doc --no-deps
|
||||
elif [ -f "*.dart" ]; then
|
||||
melos analyze
|
||||
fi
|
||||
|
||||
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 "- Langue de documentation : $DOC_LANGUAGE"
|
||||
echo "- Commentaires ajoutés : $ADDED_COMMENTS"
|
||||
echo "- Commentaires mis à jour : $UPDATED_COMMENTS"
|
||||
echo "- Erreurs : $ERRORS"
|
||||
```
|
||||
|
||||
### Critères de réussite
|
||||
|
||||
1. **Critères d'achèvement** : Réussite quand tous les éléments suivants sont satisfaits :
|
||||
- Analyse statique spécifique au langage RÉUSSIE
|
||||
- Nombre d'erreurs est 0
|
||||
- Tous les commentaires ajoutés/mis à jour respectent les standards
|
||||
|
||||
2. **Réussite partielle** : Dans les cas suivants :
|
||||
- Nombre d'erreurs inférieur à 5
|
||||
- Plus de 90% respectent les standards
|
||||
|
||||
3. **Échec** : Dans les cas suivants :
|
||||
- Analyse statique ÉCHOUÉE
|
||||
- Nombre d'erreurs est 5 ou plus
|
||||
|
||||
### Intégration avec Claude
|
||||
|
||||
```bash
|
||||
# Analyser tout le projet (détection automatique de langue)
|
||||
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
|
||||
/update-doc-string
|
||||
"Update this project's docstrings following language-specific best practices"
|
||||
# → Si les commentaires existants contiennent du français, exécuter avec fr ; sinon, exécuter avec en
|
||||
|
||||
# Exécuter explicitement avec documentation anglaise
|
||||
/update-doc-string --lang en
|
||||
"Update docstrings following language-specific best practices"
|
||||
|
||||
# Exécuter explicitement avec documentation française
|
||||
/update-doc-string --lang fr
|
||||
"Update this project's docstrings following language-specific best practices"
|
||||
|
||||
# Exécuter sans marqueurs (détection automatique de langue)
|
||||
/update-doc-string --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
|
||||
# Documentation anglaise, sans marqueurs
|
||||
/update-doc-string --lang en --marker false
|
||||
"Improve existing docstrings without adding Claude markers"
|
||||
```
|
||||
Reference in New Issue
Block a user