---
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.md`