---
description: Workflow para criação e padronização de documentação em código (JSDoc, comentários e tipagem)
---

# Workflow: Documentar Código

## 🎯 Objetivo
Estabelecer um padrão global e unificado para a redação de documentação em código (comentários, `JSDoc` e explicações arquiteturais) em todas as aplicações, garantindo clareza sem prolixidade e respeitando a política de tipagem explícita.

---

## 1️⃣ Princípios Básicos de Documentação
- **Por que, não o Quê**: Documente o raciocínio por trás da decisão arquitetural ou a regra de negócio que forçou a estratégia, não o mecanismo óbvio que o TypeScript nativamente expressaria.
- **Nomenclatura Limpa**: Confie na auto-documentação de nomes de variáveis expressivos baseados no domínio antes de escrever um comentário de texto livre.

## 2️⃣ Funções Compartilhadas e JSDoc (Obrigatória)
Toda função central ou de uso compartilhado, independente da aplicação (frontend, backend, mobile ou bibliotecas comuns), deve portar cabeçalho em `JSDoc`.

### Padrão para JSDoc
```typescript
/**
 * Busca os detalhes de uma entidade baseando-se no ID fornecido e calcula privilégios aplicáveis.
 * Não utilizar em fluxos de processamento em lote para evitar sobrecarga de requisições ou banco.
 *
 * @param tenantId  - Identificador único do cliente/tenant no sistema
 * @param entityId  - ID exclusivo identificando o registro na base de dados
 * @returns Retorna o objeto consolidado com dados ou `null` caso não seja encontrado
 */
export const obterDetalhesEntidade = async (tenantId: string, entityId: string) => { ... }
```

## 3️⃣ Tratamento de Exceções e Casts Temporários
Devido à política `TypeScript sem any`, não utilizamos conversores obscuros imperativamente.
Porém, se uma coerção agressiva (`as unknown as X`) demonstrar-se temporariamente necessária por divergência ou limitação de SDK terceiro, **o comentário justificando a anomalia é obrigatório**.

```typescript
// Necessário cast duplo pois a biblioteca externa não provê tipagem genérica adequada na versão atual
const dados = payload.raw as unknown as RespostaFormatada
```

## 4️⃣ Atribuição de TODOs
Toda refatoração, debito técnico visualizado ou dúvida de negócio deixada aberta em código de longo prazo **não prescreve** e deve ser acompanhada do formato `// TODO`:
- **Tipagem**: `// TODO de tipagem: Criar interface estrita para o retorno da API de listagem (Removendo Partial)`
- **Negócio**: `// TODO de regra: Validar com a equipe de Produto se a nova taxa adicional será inserida para clientes antigos.`

## 5️⃣ Validação do Fluxo
Sempre ao propor documentação de um arquivo novo ou refatorado, valide via checklist:
* [ ] A documentação está aderente sem estar redundante à tipagem TS?
* [ ] A formatação de parágrafos/espaçamento quebra alguma regra no formatador?
* [ ] A sintaxe suporta autocompletion na sua camada dependente (`@params` estão exatos)?

---

## Referências

- Rules: `.agent/rules/typescript-sem-any.global.md` (política de tipagem que influencia a documentação)
- Skill: `.agent/skills/documentar-decisao-tecnica/SKILL.md` (para decisões arquiteturais que exigem ADR além de JSDoc)