Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Documentação Automática

Aula 8 de 20 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Documentar Sem Interromper o Desenvolvimento
  2. Documentação Inline: JSDoc e Comentários
  3. Gerar um README
  4. Documentação de API
  5. Documentação de Arquitetura
  6. Atualizar Documentação Existente
  7. Automatizar via AGENTS.md
  8. Pontos-chave

Documentar Sem Interromper o Desenvolvimento

Todos concordam que a documentação é necessária, mas quase ninguém a escreve. Porquê? Porque a redação ocorre no pior momento possível: a funcionalidade está terminada e a atenção já mudou para outro lado. O Codex desloca este custo. Ele analisa o código tal como existe e produz documentação completa e atualizada, alinhada com a implementação real. Esta fidelidade é o fator decisivo: documentação inventada causa mais danos do que uma página em branco, pois inspira uma falsa confiança.

Documentação Inline: JSDoc e Comentários

A documentação mais consultada aparece diretamente na dica de ferramenta (tooltip) do editor, exatamente onde surge a dúvida.

"Add JSDoc documentation to all exported functions 
and types in src/lib/. Include a description, 
parameters, return type, and a usage example 
for each function."

Eis o que o Codex produz para uma função de cálculo de preço:

/**
 * Calculates the total price after applying the discount.
 * 
 * @param basePrice - Unit price in cents
 * @param quantity - Number of units (minimum 1)
 * @param discountPercent - Discount percentage (0-100)
 * @returns The total price in cents, rounded to an integer
 * 
 * @example
 * calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
 * 
 * @throws {ValidationError} If price or quantity is negative
 */
export function calculateTotal(
  basePrice: number,
  quantity: number,
  discountPercent: number = 0
): number {
  // ...
}

Duas informações aqui valem mais do que todo o resto: a unidade — cêntimos, não euros — e a exceção lançada para valores negativos. Estas são precisamente as duas coisas que um programador costuma descobrir em produção, depois de faturar os clientes dez vezes menos do que o pretendido. O Codex extraiu-as da implementação, não de um modelo de comentário genérico.

Gerar um README

Para um novo projeto, ou para um README que se tornou ficcional devido ao desvio ao longo do tempo, liste o que o leitor deve ser capaz de fazer assim que terminar a leitura.

"Generate a comprehensive README.md for this project. Include:
- Project description and purpose
- Prerequisites (Node.js, PostgreSQL, etc.)
- Step-by-step installation instructions
- Required environment variables (without values)
- Available commands (dev, test, build, lint)
- Project structure
- How to contribute"

O Codex baseia-se no package.json, nos ficheiros de configuração e na árvore de diretórios real para produzir um documento que reflete o estado atual do projeto. A instrução “without values” não é um capricho: sem ela, um agente que acabou de ler um .env.example bem preenchido poderia copiar alegremente valores que não deseja ver num ficheiro versionado.

Documentação de API

Para uma API REST, a documentação mais rentável é aquela que outras ferramentas podem consumir sem intervenção humana.

"Analyze all routes in src/api/routes/ and generate 
an openapi.yaml file. Include request and response 
schemas based on existing TypeScript types and 
Zod validations."

Tudo é extraído do código: caminhos das rotas, métodos HTTP, esquemas de validação e tipos de resposta. A especificação resultante é, portanto, fiel à implementação, permitindo aos seus consumidores derivar um cliente tipado ou uma coleção de testes sem lhe fazer uma única pergunta.

Documentação de Arquitetura

As decisões de arquitetura raramente são escritas. Quando o são, descrevem a intenção inicial e não a realidade três anos depois. Peça ao Codex para formalizar o que realmente existe no código.

"Analyze the project architecture and create a 
docs/architecture.md file documenting:
- Layers (API, services, repositories, models)
- Data flow for a typical request
- Patterns used (repository pattern, dependency injection)
- Dependencies between modules"

Este documento tem um benefício secundário inesperado: ao descrever as dependências dos módulos tal como elas realmente são, expõe acoplamentos que ninguém tinha reconhecido — como o serviço de faturação a importar um utilitário do módulo de autenticação.

Atualizar Documentação Existente

Documentação desatualizada é pior do que nenhuma documentação, pois faz perder tempo com autoridade.

"Compare README.md with the current state of the project. 
Identify outdated sections (commands that no longer exist, 
removed dependencies, incorrect instructions). 
Update the README accordingly."

O Codex confronta cada afirmação no README com o código real e corrige as inconsistências. Agende esta tarefa periodicamente, como antes de cada lançamento, em vez de descobrir a sua necessidade no dia em que um novo colaborador percebe que nenhum dos comandos de instalação funciona.

Automatizar via AGENTS.md

Para deixar de tratar a documentação como uma tarefa separada, transforme-a numa restrição permanente do projeto.

## Documentation
- Every new exported function MUST have complete JSDoc
- API changes MUST update openapi.yaml
- Comment format: French for business logic, English for technical details

Com estas três regras, cada tarefa de desenvolvimento inclui a sua própria atualização de documentação. A lacuna entre o código e a descrição deixa de alargar silenciosamente, que é a única forma sustentável de vencer esta batalha.

Pontos-chave

  • O Codex gera documentação fiel ao código real, não inventada
  • A documentação inline (JSDoc) é a mais útil para o trabalho diário
  • O Codex pode produzir READMEs, especificações OpenAPI e documentação de arquitetura
  • Utilize o Codex para detetar e corrigir documentação desatualizada
  • Adicione regras de documentação ao AGENTS.md para automatizar o processo