Gerenciar sistematicamente comentários DartDoc

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)

1. Quando comentário existente não atende aos critérios: Substituir completamente (não duplicar)
2. 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

1. Sucesso parcial: Nos seguintes casos

• Número de erros menor que 5
• 90% ou mais do total atende aos critérios

1. Falha: Nos seguintes casos

• melos analyze FALHOU
• Número de erros 5 ou mais