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 @@
|
||||
## 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
|
||||
Reference in New Issue
Block a user