Initial commit
This commit is contained in:
Zhongwei Li
202
commands/update-dart-doc.md
Normal file
202
commands/update-dart-doc.md
Normal file
@@ -0,0 +1,202 @@
|
||||
## Actualizar Documentación Dart
|
||||
|
||||
Gestiona sistemáticamente los comentarios DartDoc en archivos Dart y mantiene documentación en español de alta calidad.
|
||||
|
||||
### Uso
|
||||
|
||||
```bash
|
||||
# Realizar nuevas adiciones y actualizaciones simultáneamente
|
||||
"Agregar comentarios DartDoc a clases sin ellos y actualizar comentarios que no cumplen estándares"
|
||||
|
||||
# Verificar archivos cambiados en PR
|
||||
"Verificar si hay marcadores Claude en el DartDoc de archivos cambiados en PR #4308"
|
||||
|
||||
# Mantener documentación para directorios específicos
|
||||
"Agregar DartDoc a clases Widget bajo packages/app/lib/ui/screen/"
|
||||
|
||||
# Ejecutar sin marcadores
|
||||
/update-dart-doc --marker false
|
||||
"Mejorar DartDoc en proyecto existente (sin marcadores Claude)"
|
||||
```
|
||||
|
||||
### Opciones
|
||||
|
||||
- `--marker <true|false>` : Si agregar marcadores Claude (por defecto: true)
|
||||
|
||||
### Ejemplos Básicos
|
||||
|
||||
```bash
|
||||
# 1. Analizar archivos objetivo
|
||||
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
|
||||
"Identificar clases con DartDoc insuficiente (0 líneas o menos de 30 caracteres)"
|
||||
|
||||
# 2. Agregar documentación
|
||||
"Agregar comentarios DartDoc que contengan elementos requeridos a las clases identificadas"
|
||||
|
||||
# 3. Verificar marcadores
|
||||
"Asegurar que todos los DartDoc agregados/actualizados tengan marcadores Claude"
|
||||
```
|
||||
|
||||
### Procedimiento de Ejecución
|
||||
|
||||
#### 1. Prioridad de Elementos Objetivo
|
||||
|
||||
1. 🔴 **Prioridad más alta**: Elementos sin comentarios DartDoc (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**:
|
||||
|
||||
- Clases (todas las definiciones de clase)
|
||||
- Enums
|
||||
- Extensiones
|
||||
- Funciones importantes (funciones de nivel superior, opcional)
|
||||
|
||||
#### 2. Reglas de Escritura DartDoc
|
||||
|
||||
**Estructura básica**:
|
||||
|
||||
```dart
|
||||
/// {Resumen del elemento} (30-60 caracteres, requerido)
|
||||
///
|
||||
/// {Descripción detallada} (debe incluir rol, contexto de uso y notas, 50-200 caracteres)
|
||||
///
|
||||
/// Generado por Claude 🤖
|
||||
@annotation // No cambiar anotaciones existentes
|
||||
class ClassName {
|
||||
```
|
||||
|
||||
**Estilo de texto**:
|
||||
|
||||
- Lenguaje formal: "muestra", "es una clase que gestiona"
|
||||
- Usar puntuación española: 「.」「,」
|
||||
- Agregar espacio de ancho medio entre caracteres españoles y alfanuméricos
|
||||
- Usar español para términos técnicos: "Estado de autenticación"
|
||||
- Mantener cada línea dentro de 80 caracteres
|
||||
|
||||
#### 3. Ejemplos de Escritura por Categoría de Clase
|
||||
|
||||
**Clase de gestión de estado (Riverpod)**:
|
||||
|
||||
```dart
|
||||
/// Estado que gestiona el estado deshabilitado de gestos de deslizamiento horizontal.
|
||||
///
|
||||
/// Se utiliza cuando los deslizamientos horizontales necesitan ser deshabilitados durante pantallas u operaciones específicas,
|
||||
/// como durante visualizaciones de carrusel o entradas específicas.
|
||||
///
|
||||
/// Generado por Claude 🤖
|
||||
@Riverpod(keepAlive: true, dependencies: [])
|
||||
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
|
||||
```
|
||||
|
||||
**Clase Widget**:
|
||||
|
||||
```dart
|
||||
/// Widget que muestra un perfil de usuario.
|
||||
///
|
||||
/// Organiza verticalmente imagen de avatar, nombre de usuario e información de estado,
|
||||
/// y navega a la pantalla de detalle de perfil cuando se toca.
|
||||
///
|
||||
/// Generado por Claude 🤖
|
||||
class UserProfileWidget extends HookConsumerWidget {
|
||||
```
|
||||
|
||||
#### 4. Reglas para Preservar Contenido Existente
|
||||
|
||||
1. **Si el comentario existente cumple estándares**: Mantener como está (no agregar nuevo comentario)
|
||||
- Estándares: 30+ caracteres e incluye elementos requeridos (resumen, detalles, marcador)
|
||||
2. **Si el comentario existente no cumple estándares**: Reemplazar completamente (sin duplicación)
|
||||
3. **Si no hay comentario existente**: Agregar nuevo comentario
|
||||
|
||||
**Información importante a preservar**:
|
||||
|
||||
- URLs y enlaces: Referencias que comienzan con `Ver también:`
|
||||
- Comentarios TODO: En el formato `TODO(nombre_usuario):`
|
||||
- Notas: Advertencias como `Nota:` o `Advertencia:`
|
||||
- Ejemplos de uso: Código que comienza con `Ejemplo:` o `Uso:`
|
||||
- Restricciones técnicas: Descripciones de rendimiento o limitaciones
|
||||
|
||||
### Gestión de Marcadores Claude
|
||||
|
||||
```bash
|
||||
# Formato de marcador
|
||||
/// Generado por Claude 🤖
|
||||
|
||||
# Verificar marcadores en archivos cambiados de PR
|
||||
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generado por Claude"
|
||||
"Agregar marcadores a archivos que no los tienen"
|
||||
```
|
||||
|
||||
### 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 3 elementos - resumen, explicación detallada y marcador Claude
|
||||
- ✅ **Completitud**: Describir rol, contexto de uso y notas
|
||||
- ✅ **Consistencia**: Unificar estilo con lenguaje formal
|
||||
- ✅ **Formato**: Agregar espacio de ancho medio entre español e inglés
|
||||
- ✅ **Precisión**: Analizar implementación y solo incluir descripciones basadas en hechos
|
||||
- ✅ **Estructura**: Preservar anotaciones, colocar comentarios arriba
|
||||
- ✅ **Longitud**: Mantener cada línea dentro de 80 caracteres
|
||||
- ✅ **Marcador**: Agregar siempre marcador para cambios por Claude
|
||||
|
||||
### Notas
|
||||
|
||||
**🔴 Prohibiciones absolutas**:
|
||||
|
||||
- ❌ Cambios de código distintos a comentarios de documentación
|
||||
- ❌ Especulación sobre detalles de implementación (solo descripciones fácticas)
|
||||
- ❌ Mezcla no natural de inglés y español
|
||||
- ❌ Eliminación o modificación de anotaciones existentes
|
||||
- ❌ Duplicación con comentarios existentes
|
||||
- ❌ Comentarios bajo estándares de conteo de caracteres en archivos de prueba (`*_test.dart`)
|
||||
- ❌ Comentarios bajo estándares de conteo de caracteres en archivos VRT (`*_vrt.dart`)
|
||||
|
||||
**Análisis estático y commit**:
|
||||
|
||||
```bash
|
||||
# Registrar resultados de ejecución
|
||||
ADDED_COMMENTS=0
|
||||
UPDATED_COMMENTS=0
|
||||
ERRORS=0
|
||||
|
||||
# Verificar después de cambios
|
||||
melos analyze
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "🔴 Error: Falló análisis estático"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Generar resumen de ejecución
|
||||
echo "📊 Resultados de ejecución:"
|
||||
echo "- Comentarios agregados: $ADDED_COMMENTS"
|
||||
echo "- Comentarios actualizados: $UPDATED_COMMENTS"
|
||||
echo "- Errores: $ERRORS"
|
||||
|
||||
# Ejemplo de commit
|
||||
git commit -m "docs: Agregar y actualizar comentarios DartDoc
|
||||
|
||||
- Agregar DartDoc a clases, enums y extensiones que no cumplen estándares
|
||||
- Actualizar comentarios bajo 30 caracteres para cumplir estándares
|
||||
- Agregar uniformemente marcadores Claude
|
||||
|
||||
Resultados de ejecución:
|
||||
- Agregados: $ADDED_COMMENTS
|
||||
- Actualizados: $UPDATED_COMMENTS
|
||||
|
||||
Generado por Claude 🤖"
|
||||
```
|
||||
|
||||
### Criterios de Éxito de Ejecución
|
||||
|
||||
1. **Éxito completo**: Cuando se cumplen todos los siguientes
|
||||
- `melos analyze` PASÓ
|
||||
- 0 errores
|
||||
- Todos los comentarios agregados/actualizados cumplen estándares
|
||||
|
||||
2. **Éxito parcial**: Cuando
|
||||
- Menos de 5 errores
|
||||
- 90% o más de todos los comentarios cumplen estándares
|
||||
|
||||
3. **Falla**: Cuando
|
||||
- `melos analyze` FALLÓ
|
||||
- 5 o más errores
|
||||
Reference in New Issue
Block a user