Update Doc String

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

# Gérer les docstrings et commentaires multilingues

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"
```