.agent/rules/jsdoc-padrao.md

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

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 ✅

/**
 * 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 ❌

/**
 * 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).

// 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:

// 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