Initial commit
This commit is contained in:
Zhongwei Li
306
commands/update-doc-string.md
Normal file
306
commands/update-doc-string.md
Normal file
@@ -0,0 +1,306 @@
|
||||
## Update Doc String
|
||||
|
||||
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"
|
||||
```
|
||||
Reference in New Issue
Block a user