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)

1. Si comentarios existentes no cumplen estándares: Reemplazar completamente (sin duplicación)
2. 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

1. Éxito Parcial: En los siguientes casos:

• Número de errores menos de 5 elementos
• 90% o más cumple estándares globales

1. Fallo: En los siguientes casos:

• Análisis estático FAILED
• Número de errores 5 o más elementos