203 lines
6.9 KiB
Markdown
203 lines
6.9 KiB
Markdown
## Update Dart Doc
|
|
|
|
Gerencia sistematicamente comentários DartDoc de arquivos Dart e mantém documentação em português de alta qualidade.
|
|
|
|
### Uso
|
|
|
|
```bash
|
|
# Executar adição nova e atualização simultaneamente
|
|
"Adicione DartDoc a classes sem comentários e atualize comentários que não atendem aos critérios"
|
|
|
|
# Verificar arquivos alterados no PR
|
|
"Verifique se há marcadores Claude no DartDoc dos arquivos alterados no PR #4308"
|
|
|
|
# Organizar documentação de diretório específico
|
|
"Adicione DartDoc às classes Widget em packages/app/lib/ui/screen/"
|
|
|
|
# Executar sem marcador
|
|
/update-dart-doc --marker false
|
|
"Melhore o DartDoc do projeto existente (sem adicionar marcadores Claude)"
|
|
```
|
|
|
|
### Opções
|
|
|
|
- `--marker <true|false>` : Se deve adicionar marcadores Claude (padrão: true)
|
|
|
|
### Exemplos básicos
|
|
|
|
```bash
|
|
# 1. Análise de arquivos alvo
|
|
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
|
|
"Identifique classes com DartDoc insuficiente (0 linhas de comentário ou menos de 30 caracteres)"
|
|
|
|
# 2. Adição de documentação
|
|
"Adicione comentários DartDoc contendo elementos essenciais às classes identificadas"
|
|
|
|
# 3. Verificação de marcador
|
|
"Confirme que todos os DartDoc adicionados/atualizados possuem marcadores Claude"
|
|
```
|
|
|
|
### Procedimento de execução
|
|
|
|
#### 1. Prioridade dos elementos alvo
|
|
|
|
1. 🔴 **Máxima prioridade**: Elementos sem comentários DartDoc (0 linhas de comentário)
|
|
2. 🟡 **Próxima prioridade**: Elementos que não atendem aos critérios (menos de 30 caracteres ou falta elementos essenciais)
|
|
3. 🟢 **Alvo de verificação**: Comentários existentes sem marcadores Claude
|
|
|
|
**Elementos alvo**:
|
|
|
|
- Class (todas as definições de classe)
|
|
- Enum (tipos enumerados)
|
|
- Extension (métodos de extensão)
|
|
- Funções importantes (funções de nível superior, opcionais)
|
|
|
|
#### 2. Regras de escrita DartDoc
|
|
|
|
**Estrutura básica**:
|
|
|
|
```dart
|
|
/// {Descrição resumida do elemento} (30-60 caracteres, obrigatório)
|
|
///
|
|
/// {Descrição detalhada} (função, contexto de uso, pontos de atenção obrigatórios, 50-200 caracteres)
|
|
///
|
|
/// Generated by Claude 🤖
|
|
@Anotacao // Não alterar anotações existentes
|
|
class NomeClasse {
|
|
```
|
|
|
|
**Estilo de escrita**:
|
|
|
|
- Linguagem formal: "exibe", "é uma classe que gerencia"
|
|
- Pontuação usa "." e ","
|
|
- Espaço entre português e caracteres alfanuméricos
|
|
- Termos técnicos em português: "estado de Authentication"
|
|
- Cada linha dentro de 80 caracteres
|
|
|
|
#### 3. Exemplos de descrição por categoria de classe
|
|
|
|
**Classes de gerenciamento de estado (Riverpod)**:
|
|
|
|
```dart
|
|
/// State que gerencia o estado de desativação de gestos de swipe horizontal.
|
|
///
|
|
/// Usado quando é necessário desativar swipe horizontal em telas específicas
|
|
/// ou durante operações. Por exemplo, durante exibição de carrossel ou entrada específica.
|
|
///
|
|
/// Generated by Claude 🤖
|
|
@Riverpod(keepAlive: true, dependencies: [])
|
|
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
|
|
```
|
|
|
|
**Classes Widget**:
|
|
|
|
```dart
|
|
/// Widget que exibe o perfil do usuário.
|
|
///
|
|
/// Organiza verticalmente imagem de avatar, nome de usuário e informações de status,
|
|
/// fazendo transição para tela de detalhes do perfil ao tocar.
|
|
///
|
|
/// Generated by Claude 🤖
|
|
class UserProfileWidget extends HookConsumerWidget {
|
|
```
|
|
|
|
#### 4. Regras de preservação de conteúdo existente
|
|
|
|
1. **Quando comentário existente atende aos critérios**: Preservar como está (não adicionar novo)
|
|
- Critérios: 30+ caracteres e contém elementos essenciais (resumo, detalhes, marcador)
|
|
2. **Quando comentário existente não atende aos critérios**: Substituir completamente (não duplicar)
|
|
3. **Quando não há comentário existente**: Adicionar novo comentário
|
|
|
|
**Informações importantes a preservar**:
|
|
|
|
- URLs e links: Referências começando com `See also:`
|
|
- Comentários TODO: Formato `TODO(nome_usuario):`
|
|
- Avisos: Alertas como `Atenção:` ou `Warning:`
|
|
- Exemplos de uso: Código começando com `Exemplo:` ou `Example:`
|
|
- Restrições técnicas: Descrições de performance ou limitações
|
|
|
|
### Gerenciamento de marcadores Claude
|
|
|
|
```bash
|
|
# Formato do marcador
|
|
/// Generated by Claude 🤖
|
|
|
|
# Verificação de marcador em arquivos alterados no PR
|
|
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
|
|
"Adicione marcadores aos arquivos sem marcador"
|
|
```
|
|
|
|
### Lista de verificação de qualidade
|
|
|
|
- ✅ **Contagem de caracteres**: Respeitar rigorosamente resumo 30-60 caracteres, detalhes 50-200 caracteres
|
|
- ✅ **Elementos essenciais**: Incluir obrigatoriamente 3 elementos: resumo, descrição detalhada, marcador Claude
|
|
- ✅ **Completude**: Descrever função, contexto de uso, pontos de atenção
|
|
- ✅ **Consistência**: Unificar estilo em linguagem formal
|
|
- ✅ **Formatação**: Espaço entre português e inglês
|
|
- ✅ **Precisão**: Analisar implementação e descrever apenas fatos
|
|
- ✅ **Estrutura**: Preservar anotações, posicionar comentários acima
|
|
- ✅ **Comprimento**: Cada linha dentro de 80 caracteres
|
|
- ✅ **Marcador**: Adicionar obrigatoriamente marcador para alterações feitas por Claude
|
|
|
|
### Observações
|
|
|
|
**🔴 Itens absolutamente proibidos**:
|
|
|
|
- ❌ Alterações de código além de comentários de documentação
|
|
- ❌ Suposições sobre detalhes de implementação (descrever apenas fatos)
|
|
- ❌ Mistura não natural de inglês e português
|
|
- ❌ Remoção ou alteração de anotações existentes
|
|
- ❌ Duplicação com comentários existentes
|
|
- ❌ Comentários abaixo do critério de caracteres em arquivos de teste (`*_test.dart`)
|
|
- ❌ Comentários abaixo do critério de caracteres em arquivos VRT (`*_vrt.dart`)
|
|
|
|
**Análise estática e commit**:
|
|
|
|
```bash
|
|
# Registro de resultados de execução
|
|
ADDED_COMMENTS=0
|
|
UPDATED_COMMENTS=0
|
|
ERRORS=0
|
|
|
|
# Verificação após alteração
|
|
melos analyze
|
|
if [ $? -ne 0 ]; then
|
|
echo "🔴 Erro: Análise estática falhou"
|
|
exit 1
|
|
fi
|
|
|
|
# Saída do resumo de execução
|
|
echo "📊 Resultado da execução:"
|
|
echo "- Comentários adicionados: $ADDED_COMMENTS itens"
|
|
echo "- Comentários atualizados: $UPDATED_COMMENTS itens"
|
|
echo "- Número de erros: $ERRORS itens"
|
|
|
|
# Exemplo de commit
|
|
git commit -m "docs: adicionar e atualizar comentários DartDoc
|
|
|
|
- Adicionar DartDoc a classes, enum, extension que não atendem aos critérios
|
|
- Atualizar comentários com menos de 30 caracteres conforme critérios
|
|
- Adicionar marcadores Claude uniformemente
|
|
|
|
Resultado da execução:
|
|
- Adicionados: $ADDED_COMMENTS itens
|
|
- Atualizados: $UPDATED_COMMENTS itens
|
|
|
|
Generated by Claude 🤖"
|
|
```
|
|
|
|
### Critérios de sucesso da execução
|
|
|
|
1. **Determinação de conclusão**: Sucesso quando atende a todos os seguintes
|
|
- `melos analyze` PASSOU
|
|
- Número de erros é 0
|
|
- Todos os comentários adicionados/atualizados atendem aos critérios
|
|
|
|
2. **Sucesso parcial**: Nos seguintes casos
|
|
- Número de erros menor que 5
|
|
- 90% ou mais do total atende aos critérios
|
|
|
|
3. **Falha**: Nos seguintes casos
|
|
- `melos analyze` FALHOU
|
|
- Número de erros 5 ou mais
|