203 lines
6.8 KiB
Markdown
203 lines
6.8 KiB
Markdown
## 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
|