## 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