---
type: rule
name: jsdoc-padrao
description: Padrões de documentação em código-fonte (comentários claros e coerentes quanto à aplicação, JSDoc, casts e TODOs).
scope: global
trigger: file_match
globs:
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.vue"
  - "**/*.js"
updatedAt: "2026-09-01"
---

# Regra: Documentação e Comentários no Código-Fonte

## 1. Princípio Fundamental

> **O código-fonte deve receber comentários claros e coerentes quanto à sua aplicação.**

Comentários no código-fonte não existem para descrever o óbvio sintático (que a tipagem TypeScript já fornece), mas sim para **explicar o propósito prático, o contexto operacional no sistema e as regras de negócio** que regem aquela função, método, componente ou rota.

---

## 2. JSDoc Obrigatório em Funções, Serviços, Rotas e Composables

Toda função central, serviço de negócio (`servicos/`), endpoint/rota (`rotas/`), query de banco (`banco/`), composable (`composables/`) ou método compartilhado deve possuir cabeçalho JSDoc com:

1. **Descrição da Aplicação Prática**: Para que serve no sistema e em quais cenários operacionais é utilizada.
2. **Contexto de Negócio / Regras**: Restrições, validações críticas e impactos em outras partes da aplicação.
3. **Parâmetros (`@param`)**: Significado contextual de cada parâmetro (não apenas repetir o nome).
4. **Retorno (`@returns`)**: Estrutura e significado do valor retornado em sucesso ou falha/nulo.
5. **Efeitos Colaterais / Exceções (`@throws`)**: Filas disparadas, transações, logs ou erros esperados.

### Exemplo Correto ✅

```typescript
/**
 * Calcula o balanço volumétrico e a carga de efluentes tratados para o período informado.
 * Aplica as diretrizes da Resolução CONAMA nº 430/2011 e regras de tolerância do ponto de descarte.
 *
 * Aplicação: Utilizado na geração do relatório mensal e no cálculo de conformidade antes do envio de alertas.
 *
 * @param tenantId  - Identificador do empreendimento no sistema
 * @param pontoId   - ID do ponto de monitoramento cadastrado
 * @param periodo   - Intervalo de datas para consolidação das leituras
 * @returns Balanço consolidado contendo vazão média, picos e índice de conformidade
 * @throws {ErroValidacaoParametros} Se o ponto não possuir medições no período
 */
export const calcularBalancoEfluentes = async (
  tenantId: string,
  pontoId: string,
  periodo: IntervaloDatas
): Promise<BalancoConsolidado> => { ... }
```

### Exemplo Incorreto ❌

```typescript
/**
 * Calcula efluentes.
 * @param tenantId string
 * @param pontoId string
 * @param periodo object
 */
export const calcularBalancoEfluentes = async (...) => { ... }
```

---

## 3. Comentários Inline Contextuais e Expressivos

Use comentários inline (`//`) para esclarecer:
- Decisões de cálculo e fórmulas não-triviais.
- Tratamento de casos de borda e regras de exceção.
- Ordem de execução de passos críticos (ex: pipeline de transformação de dados).

```typescript
// Regra: se o pH estiver fora da faixa 6.0-9.0, o registro é marcado como não-conforme
const estaConforme = leitura.ph >= 6.0 && leitura.ph <= 9.0
```

---

## 4. Casts Temporários — Justificativa Obrigatória

Qualquer coerção de tipo (`as unknown as T`, `as T`) exige comentário explicando o motivo técnico:

```typescript
// Necessário: biblioteca de terceiros não exporta a tipagem dos metadados na v2
const metadados = resposta.raw as unknown as MetadadosConexao
```

---

## 5. TODOs Estruturados

Dívidas técnicas ou dúvidas de negócio devem ser registradas de forma padronizada:

- **Tipagem**: `// TODO de tipagem: Migrar retorno bruto para schema Zod zBalancoRetorno`
- **Negócio**: `// TODO de regra: Confirmar com Operador se tolerância de DBO aplica-se a descarte pluvial`

---

## Impacto

Código autoexplicativo e devidamente contextualizado acelera a manutenção, evita regressões de regras e permite que desenvolvedores e agentes de IA compreendam instantaneamente o impacto de qualquer alteração.

---

## Referências

- Rule: `rules/ddd-documentacao-primeiro.md`
- Rule: `rules/regras-negocio-md.md`
- Rule: `rules/typescript-sem-any.md`