---
description: 'Gestionar docstrings y comentarios multilingüe. Se activa con "actualizar docstrings", "gestionar comentarios".'
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
---

# Gestionar docstrings y comentarios multilingüe

Gestionar sistemáticamente docstrings/comentarios multilingües y mantener documentación de alta calidad.

## Uso

```bash
# Ejecutar con detección automática de idioma
"Por favor agregar docstrings a clases y funciones sin ellos, y actualizar comentarios que no cumplan estándares"

# Ejecutar con idioma especificado
/update-doc-string --lang python
"Por favor actualizar docstrings en archivos Python para cumplir con PEP 257"

# Mantener documentación para directorios específicos
"Por favor agregar JSDoc a funciones bajo src/components/"
```

## Opciones

- `--lang <es|en|ja>` : Idioma de documentación (por defecto: auto-detectado de comentarios existentes, sino es)
- `--style <estilo>` : Especificar estilo de documentación (tiene valores por defecto específicos del idioma)
- `--marker <true|false>` : Si agregar marcadores Claude (por defecto: true)

## Ejemplos Básicos

```bash
# 1. Analizar archivos objetivo (lenguaje de programación auto-detectado)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
"Por favor identificar elementos con docstrings insuficientes (0 líneas de comentario o menos de 30 caracteres)"

# 2. Agregar documentación (detección automática de idioma)
"Por favor agregar docstrings que contengan elementos requeridos específicos del idioma a los elementos identificados"
# → Si comentarios existentes contienen español, escribir en español; sino, escribir en inglés

# 3. Agregar documentación (especificar explícitamente español)
/update-doc-string --lang es
"Agregar docstrings con elementos requeridos a los elementos identificados"

# 4. Verificar marcadores
"Por favor confirmar que todos los docstrings agregados/actualizados tienen marcadores Claude"
```

## Pasos de Ejecución

### 1. Prioridad de Elementos Objetivo

1. 🔴 **Prioridad Más Alta**: Elementos sin docstrings/comentarios (0 líneas de comentario)
2. 🟡 **Siguiente Prioridad**: Elementos que no cumplen estándares (menos de 30 caracteres o elementos requeridos faltantes)
3. 🟢 **Objetivo de Verificación**: Comentarios existentes sin marcadores Claude

**Elementos Objetivo (Comunes Entre Idiomas)**:

- Definiciones de clase
- Funciones/métodos
- Módulos (Python, Go)
- Enums
- Interfaces (TypeScript, Go)

### 2. Reglas de Documentación Específicas del Idioma

**Python (PEP 257)**:

```python
# Versión en español (por defecto)
def calculate_total(items: List[Item]) -> float:
    """Calcular el monto total para una lista de elementos. (30-60 caracteres)

    Multiplica el precio y cantidad de cada elemento y devuelve
    el total con impuestos. Devuelve 0.0 para listas vacías. (50-200 caracteres)

    Args:
        items: Lista de elementos a calcular

    Returns:
        Monto total con impuestos

    Generado por Claude 🤖
    """

# Versión en inglés (--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
/**
 * Componente que muestra un perfil de usuario. (30-60 caracteres)
 *
 * Muestra imagen de avatar, nombre de usuario e información de estado,
 * y navega a la pantalla de detalle de perfil cuando se hace clic. (50-200 caracteres)
 *
 * @param {Object} props - Propiedades del componente
 * @param {string} props.userId - ID del usuario
 * @param {boolean} [props.showStatus=true] - Bandera de visualización de estado
 * @returns {JSX.Element} Componente renderizado
 *
 * @generated by Claude 🤖
 */
const UserProfile = ({ userId, showStatus = true }) => {
```

**Go**:

```go
// CalculateTotal calcula el monto total para una lista de elementos. (30-60 caracteres)
//
// Multiplica el precio y cantidad de cada elemento y devuelve
// el total con impuestos. Devuelve 0.0 para slices vacíos. (50-200 caracteres)
//
// Generado por Claude 🤖
func CalculateTotal(items []Item) float64 {
```

**Rust**:

```rust
/// Calcular el monto total para una lista de elementos. (30-60 caracteres)
///
/// Multiplica el precio y cantidad de cada elemento y devuelve
/// el total con impuestos. Devuelve 0.0 para vectores vacíos. (50-200 caracteres)
///
/// Generado por Claude 🤖
pub fn calculate_total(items: &[Item]) -> f64 {
```

### 3. Reglas de Retención de Contenido Existente

1. **Si comentarios existentes cumplen estándares**: Mantener como están (no agregar nuevos)
   - Estándares: Al menos 30 caracteres e incluye elementos requeridos (resumen, detalles, marcador)
2. **Si comentarios existentes no cumplen estándares**: Reemplazar completamente (sin duplicación)
3. **Si no hay comentarios existentes**: Agregar nuevos comentarios

**Información Importante a Retener**:

- URLs y enlaces: `Ver también:`, `@see`, `Referencias:` etc.
- Comentarios TODO: formato `TODO:`, `FIXME:`, `XXX:`
- Notas: `Nota:`, `Advertencia:`, `Importante:` etc.
- Ejemplos: `Ejemplo:`, `Uso:`, `# Ejemplos` etc.
- Descripciones existentes de parámetros y valores de retorno

## Configuraciones Específicas del Idioma

```yaml
# Configuraciones por defecto específicas del idioma
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: "///"
```

## Lista de Verificación de Calidad

- ✅ **Conteo de Caracteres**: Adherir estrictamente a 30-60 caracteres para resumen, 50-200 para detalles
- ✅ **Elementos Requeridos**: Incluir siempre resumen, descripción detallada y marcador Claude
- ✅ **Completitud**: Describir rol, contexto de uso y notas
- ✅ **Convenciones de Idioma**: Cumplir con guías de estilo oficiales para cada idioma
- ✅ **Excepciones**: Explicar errores y excepciones (cuando aplique)
- ✅ **Precisión**: Analizar implementación y solo incluir descripciones basadas en hechos

## Notas

**🔴 Prohibiciones Estrictas**:

- ❌ Cambios de código distintos a comentarios de documentación
- ❌ Especulación sobre detalles de implementación (solo hechos)
- ❌ Formatos que violan convenciones del idioma
- ❌ Eliminación o modificación de anotaciones de tipo existentes
- ❌ Duplicación con comentarios existentes
- ❌ Comentarios bajo estándares de conteo de caracteres en archivos de prueba

## Integración con Claude

```bash
# Analizar proyecto completo (detección automática de idioma)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
/update-doc-string
"Actualizar docstrings de este proyecto siguiendo mejores prácticas específicas del idioma"
# → Si comentarios existentes contienen español, ejecutar con es; sino, ejecutar con en

# Ejecutar explícitamente con documentación en inglés
/update-doc-string --lang en
"Actualizar docstrings siguiendo mejores prácticas específicas del idioma"

# Ejecutar explícitamente con documentación en español
/update-doc-string --lang es
"Actualizar docstrings de este proyecto siguiendo mejores prácticas específicas del idioma"

# Ejecutar sin marcadores (detección automática de idioma)
/update-doc-string --marker false
"Mejorar docstrings existentes sin agregar marcadores Claude"
```

## Criterios de Éxito en Ejecución

**Métricas de Calidad**

- Cobertura de documentación: 95%+ para funciones públicas
- Consistencia de formato: 100% adherencia al estilo del proyecto
- Precisión técnica: Verificación manual de ejemplos complejos

**Indicadores de Finalización**

- Todos los elementos identificados tienen documentación apropiada
- La documentación sigue las convenciones del lenguaje
- Los ejemplos de código son ejecutables y precisos

## Configuración del Sistema

```bash
# Variables de entorno para personalización
export DOC_LANGUAGE="es"     # Idioma de documentación (es/en)
export ADDED_COMMENTS=0      # Contador de comentarios agregados
export UPDATED_COMMENTS=0    # Contador de comentarios actualizados
export ERRORS=0              # Contador de errores

# Verificación de herramientas requeridas
if command -v pylint &> /dev/null; then
  pylint --version
fi

if command -v eslint &> /dev/null; then
  eslint --version
fi

# Análisis estático específico del lenguaje
if [ -f "*.py" ]; then
  python -m py_compile *.py
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
  npm run lint
elif [ -f "*.dart" ]; then
  melos analyze
fi

if [ $? -ne 0 ]; then
  echo "🔴 Error: Análisis estático falló"
  exit 1
fi

# Resumen de ejecución
echo "📊 Resultados de ejecución:"
echo "- Idioma de documentación: $DOC_LANGUAGE"
echo "- Comentarios agregados: $ADDED_COMMENTS elementos"
echo "- Comentarios actualizados: $UPDATED_COMMENTS elementos"
echo "- Número de errores: $ERRORS elementos"
```

## Validación de Calidad Final

**Criterios de Completitud**

1. **Juicio de Finalización**: Exitoso cuando se cumplen todos los siguientes:
   - Análisis estático específico del lenguaje PASSED
   - Número de errores es 0
   - Todos los comentarios agregados/actualizados cumplen estándares

2. **Éxito Parcial**: En los siguientes casos:
   - Número de errores menos de 5 elementos
   - 90% o más cumple estándares globales

3. **Fallo**: En los siguientes casos:
   - Análisis estático FAILED
   - Número de errores 5 o más elementos