59 lines
1.8 KiB
Markdown
59 lines
1.8 KiB
Markdown
---
|
|
type: rule
|
|
name: jsdoc-padrao
|
|
description: Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados)
|
|
scope: global
|
|
trigger: file_match
|
|
globs:
|
|
- "**/*.ts"
|
|
- "**/*.tsx"
|
|
- "**/*.vue"
|
|
updatedAt: "2026-06-01"
|
|
---
|
|
|
|
# Regra: Documentação em Código
|
|
|
|
## 1. JSDoc — Princípios
|
|
|
|
- **Por que, não o Quê**: documente o raciocínio, não o mecanismo que o TypeScript já expressa.
|
|
- **Nomenclatura limpa**: confie em nomes expressivos antes de comentários.
|
|
|
|
## 2. JSDoc obrigatório em funções compartilhadas
|
|
|
|
Toda função central ou de uso compartilhado deve ter cabeçalho JSDoc:
|
|
|
|
```typescript
|
|
/**
|
|
* Busca detalhes da entidade e calcula privilégios aplicáveis.
|
|
* Não utilizar em processamento em lote para evitar sobrecarga.
|
|
*
|
|
* @param tenantId - Identificador do tenant no sistema
|
|
* @param entityId - ID do registro na base de dados
|
|
* @returns Objeto consolidado ou `null` se não encontrado
|
|
*/
|
|
export const obterDetalhes = async (tenantId: string, entityId: string) => { ... }
|
|
```
|
|
|
|
## 3. Casts temporários — justificativa obrigatória
|
|
|
|
Coerções agressivas requerem comentário explicando o porquê:
|
|
|
|
```typescript
|
|
// Necessário: biblioteca externa não provê tipagem genérica na versão atual
|
|
const dados = payload.raw as unknown as RespostaFormatada
|
|
```
|
|
|
|
## 4. TODOs estruturados
|
|
|
|
Dívida técnica ou dúvida de negócio deve seguir formato padronizado:
|
|
|
|
- **Tipagem**: `// TODO de tipagem: Criar interface para o retorno da API`
|
|
- **Negócio**: `// TODO de regra: Validar com Produto se taxa se aplica a clientes antigos`
|
|
|
|
## Impacto
|
|
|
|
Sem este padrão, funções compartilhadas ficam sem documentação, casts aparecem sem justificativa, e TODOs são inconsistentes e difíceis de buscar.
|
|
|
|
## Referências
|
|
|
|
- Rule: `global/rules/typescript-sem-any`
|