Update Doc String

---
description: 'Gerenciar docstrings e comentários multilíngue. Ativa com "atualizar docstrings", "gerenciar comentários".'
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
---

# Gerenciar docstrings e comentários multilíngue

Gerencia sistematicamente docstrings/comentários multilíngues e mantém documentação de alta qualidade.

## Uso

```bash
# Executar com detecção automática de idioma
"Adicione docstrings a classes e funções sem comentários e atualize comentários que não atendem aos critérios"

# Executar especificando idioma
/update-doc-string --lang python
"Atualize docstrings de arquivos Python em conformidade com PEP 257"

# Organizar documentação de diretório específico
"Adicione JSDoc às funções em src/components/"
```

## Opções

- `--lang <en|pt>` : Idioma de descrição da documentação (padrão: detecção automática dos comentários existentes, pt se não houver)
- `--style <estilo>` : Especificar estilo de documentação (com padrões específicos por idioma)
- `--marker <true|false>` : Se deve adicionar marcadores Claude (padrão: true)

## Exemplos básicos

```bash
# 1. Análise de arquivos alvo (detecção automática da linguagem de programação)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
"Identifique elementos com docstring insuficiente (0 linhas de comentário ou menos de 30 caracteres)"

# 2. Adição de documentação (detecção automática de idioma)
"Adicione docstring com elementos essenciais específicos do idioma aos elementos identificados"
# → Se houver japonês nos comentários existentes, escrever em japonês, senão em inglês

# 3. Adição de documentação (especificação explícita de inglês)
/update-doc-string --lang en
"Add docstrings with required elements to the identified elements"

# 4. Verificação de marcador
"Confirme que todas as docstrings adicionadas/atualizadas possuem marcadores Claude"
```

## Procedimento de execução

### 1. Prioridade dos elementos alvo

1. 🔴 **Máxima prioridade**: Elementos sem docstring/comentários (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 (comum a todas as linguagens)**:

- Class/definições de classe
- Function/funções e métodos
- Module/módulos (Python, Go)
- Enum/tipos enumerados
- Interface/interfaces (TypeScript, Go)

### 2. Regras de escrita por idioma

**Python (PEP 257)**:

```python
# Versão em português (padrão)
def calculate_total(items: List[Item]) -> float:
    """Calcula o valor total de uma lista de itens. (30-60 caracteres)

    Multiplica o preço e quantidade de cada item e retorna o total
    com impostos. Retorna 0.0 para listas vazias. (50-200 caracteres)

    Args:
        items: Lista de itens para cálculo

    Returns:
        Valor total com impostos

    Generated by Claude 🤖
    """

# Versão em inglês (--lang en)
def calculate_total(items: List[Item]) -> float:
    """Calculate the total amount for a list of items. (30-60 chars)

    Multiplies the price and quantity of each item and returns
    the total with tax. Returns 0.0 for empty lists. (50-200 chars)

    Args:
        items: List of items to calculate

    Returns:
        Total amount with tax

    Generated by Claude 🤖
    """
```

**JavaScript/TypeScript (JSDoc)**:

```javascript
/**
 * Componente que exibe o perfil do usuário. (30-60 caracteres)
 *
 * Exibe imagem de avatar, nome de usuário e informações de status,
 * fazendo transição para tela de detalhes do perfil ao clicar. (50-200 caracteres)
 *
 * @param {Object} props - Propriedades do componente
 * @param {string} props.userId - ID do usuário
 * @param {boolean} [props.showStatus=true] - Flag de exibição de status
 * @returns {JSX.Element} Componente renderizado
 *
 * @generated by Claude 🤖
 */
const UserProfile = ({ userId, showStatus = true }) => {
```

**Go**:

```go
// CalculateTotal calcula o valor total de uma lista de itens. (30-60 caracteres)
//
// Multiplica o preço e quantidade de cada item e retorna o total
// com impostos. Retorna 0.0 para slices vazios. (50-200 caracteres)
//
// Generated by Claude 🤖
func CalculateTotal(items []Item) float64 {
```

**Rust**:

```rust
/// Calcula o valor total de uma lista de itens. (30-60 caracteres)
///
/// Multiplica o preço e quantidade de cada item e retorna o total
/// com impostos. Retorna 0.0 para vetores vazios. (50-200 caracteres)
///
/// Generated by Claude 🤖
pub fn calculate_total(items: &[Item]) -> f64 {
```

**Dart (DartDoc)**:

```dart
/// Widget que exibe o perfil do usuário. (30-60 caracteres)
///
/// 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. (50-200 caracteres)
///
/// Generated by Claude 🤖
class UserProfileWidget extends StatelessWidget {
```

### 3. 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: `See also:`, `@see`, `Veja também:` etc.
- Comentários TODO: Formatos `TODO:`, `FIXME:`, `XXX:`
- Avisos: `Note:`, `Warning:`, `Atenção:` etc.
- Exemplos de uso: `Example:`, `Exemplo:`, `# Examples` etc.
- Descrições existentes de parâmetros e valores de retorno

## Configurações por idioma

```yaml
# Configurações padrão por idioma
languages:
  python:
    style: "google" # google, numpy, sphinx
    indent: 4
    quotes: '"""'

  javascript:
    style: "jsdoc"
    indent: 2
    prefix: "/**"
    suffix: "*/"

  typescript:
    style: "tsdoc"
    indent: 2
    prefix: "/**"
    suffix: "*/"

  go:
    style: "godoc"
    indent: 0
    prefix: "//"

  rust:
    style: "rustdoc"
    indent: 0
    prefix: "///"

  dart:
    style: "dartdoc"
    indent: 0
    prefix: "///"
```

## 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
- ✅ **Convenções da linguagem**: Conformidade com guias de estilo oficiais de cada linguagem
- ✅ **Exceções**: Descrição de erros e exceções (quando aplicável)
- ✅ **Precisão**: Analisar implementação e descrever apenas fatos

## 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)
- ❌ Formatos que violam convenções da linguagem
- ❌ Remoção ou alteração de anotações de tipo existentes
- ❌ Duplicação com comentários existentes
- ❌ Comentários abaixo do critério de caracteres em arquivos de teste

**Execução e verificação**:

```bash
# Registro de resultados de execução
ADDED_COMMENTS=0
UPDATED_COMMENTS=0
ERRORS=0

# Detecção automática de idioma dos comentários existentes
# Se detectar padrões portugueses comuns → pt, senão en
DOC_LANGUAGE="en"  # padrão
if grep -r 'ção\|ões\|agem\|ário\|ória\|ência\|português\|brasil' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
  DOC_LANGUAGE="pt"
fi

# Detecção automática de linguagem de programação e análise estática
if [ -f "*.py" ]; then
  pylint --disable=all --enable=missing-docstring .
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
  eslint . --rule 'jsdoc/require-jsdoc: error'
elif [ -f "*.go" ]; then
  golint ./...
elif [ -f "*.rs" ]; then
  cargo doc --no-deps
elif [ -f "*.dart" ]; then
  melos analyze
fi

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 "- Idioma da documentação: $DOC_LANGUAGE"
echo "- Comentários adicionados: $ADDED_COMMENTS itens"
echo "- Comentários atualizados: $UPDATED_COMMENTS itens"
echo "- Número de erros: $ERRORS itens"
```

## Critérios de sucesso da execução

1. **Determinação de conclusão**: Sucesso quando atende a todos os seguintes
   - Análise estática específica da linguagem 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
   - Análise estática FALHOU
   - Número de erros 5 ou mais

## Integração com Claude

```bash
# Análise de projeto inteiro (detecção automática de idioma)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
/update-doc-string
"Atualize as docstrings deste projeto seguindo as melhores práticas específicas de cada linguagem"
# → Se houver japonês nos comentários existentes, executa em ja, senão en

# Execução explícita em inglês
/update-doc-string --lang en
"Update docstrings following language-specific best practices"

# Execução explícita em japonês
/update-doc-string --lang pt
"Atualize as docstrings deste projeto seguindo as melhores práticas específicas de cada linguagem"

# Execução sem marcador (detecção automática de idioma)
/update-doc-string --marker false
"Improve existing docstrings without adding Claude markers"

# Documentação em inglês, sem marcador
/update-doc-string --lang en --marker false
"Improve existing docstrings without adding Claude markers"
```