Initial commit

2025-11-30 09:05:32 +08:00
commit 5c74f5699f
51 changed files with 11373 additions and 0 deletions
--- a/commands/update-doc-string.md
+++ b/commands/update-doc-string.md
@@ -0,0 +1,305 @@
+## Actualizar Doc String
+
+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