9.7 KiB
9.7 KiB
Update Doc String
Gerencia sistematicamente docstrings/comentários multilíngues e mantém documentação de alta qualidade.
Uso
# 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
# 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
- 🔴 Máxima prioridade: Elementos sem docstring/comentários (0 linhas de comentário)
- 🟡 Próxima prioridade: Elementos que não atendem aos critérios (menos de 30 caracteres ou falta elementos essenciais)
- 🟢 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):
# 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):
/**
* 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:
// 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:
/// 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):
/// 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
- 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)
- Quando comentário existente não atende aos critérios: Substituir completamente (não duplicar)
- 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:,# Examplesetc. - Descrições existentes de parâmetros e valores de retorno
Configurações por idioma
# 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:
# 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
-
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
-
Sucesso parcial: Nos seguintes casos
- Número de erros menor que 5
- 90% ou mais do total atende aos critérios
-
Falha: Nos seguintes casos
- Análise estática FALHOU
- Número de erros 5 ou mais
Integração com Claude
# 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"