Como gerar documentação automática em projetos JS

Por que automatizar a documentação em JavaScript?

Manter documentação manual em projetos JavaScript é uma tarefa ingrata. O código evolui rapidamente, novas funções são adicionadas, parâmetros mudam de nome, e a documentação estática rapidamente se torna um repositório de informações desatualizadas. O custo dessa manutenção manual é alto: desenvolvedores perdem confiança na documentação, novos integrantes da equipe enfrentam curvas de aprendizado mais íngremes, e APIs públicas geram mais dúvidas do que respostas.

A documentação automática resolve esse problema ao extrair informações diretamente do código-fonte. Comentários estruturados, tipos e anotações tornam-se a fonte única da verdade. Quando o código muda, a documentação é regenerada, mantendo-se sempre atualizada.

É importante distinguir dois tipos principais de documentação:
- Documentação de código: descreve funções, classes, parâmetros e retornos (gerada por ferramentas como JSDoc ou TypeDoc)
- Documentação de projeto: abrange guias, tutoriais e visão geral (geralmente em Markdown, que pode ser integrada ao fluxo de geração)

Ferramentas essenciais para documentação automática

JSDoc: o padrão de mercado para comentários em JS

JSDoc é a ferramenta mais consolidada para documentar código JavaScript puro. Ela interpreta comentários com anotações especiais e gera documentação em HTML, Markdown ou JSON.

Exemplo básico de comentário JSDoc:

/**
 * Calcula o preço total com imposto
 * @param {number} precoBase - Valor sem imposto
 * @param {number} taxaImposto - Percentual do imposto (0 a 1)
 * @returns {number} Preço final com imposto aplicado
 * @example
 * // retorna 120
 * calcularPrecoFinal(100, 0.2)
 */
function calcularPrecoFinal(precoBase, taxaImposto) {
  return precoBase * (1 + taxaImposto);
}

TypeScript: tipos como documentação inline

TypeScript eleva a documentação a outro nível. Os tipos são parte da linguagem, e ferramentas como TypeDoc podem gerar documentação completa a partir de interfaces e tipos, complementados por comentários.

Comparativo rápido:
- JSDoc: funciona em qualquer código JS, mas requer comentários extensos
- TypeScript: tipos são verificados em tempo de compilação, documentação é mais concisa

Para projetos novos, TypeScript com TypeDoc é a recomendação moderna. Para projetos JS legados, JSDoc é a escolha pragmática.

Configurando o JSDoc em um projeto JavaScript puro

Instalação e configuração

npm install --save-dev jsdoc

Crie um arquivo jsdoc.json na raiz do projeto:

{
  "source": {
    "include": ["src"],
    "includePattern": ".js$"
  },
  "opts": {
    "destination": "docs",
    "recurse": true
  },
  "plugins": ["plugins/markdown"],
  "templates": {
    "cleverLinks": true
  }
}

Anotações fundamentais

Além de @param e @returns, use:

  • @typedef para definir tipos personalizados
  • @example para incluir exemplos de uso
  • @throws para documentar exceções
  • @deprecated para marcar funções obsoletas

Exemplo completo:

/**
 * @typedef {Object} Usuario
 * @property {number} id - Identificador único
 * @property {string} nome - Nome completo
 * @property {string} [email] - Email (opcional)
 */

/**
 * Busca um usuário pelo ID
 * @param {number} id - ID do usuário
 * @returns {Promise<Usuario>} Dados do usuário
 * @throws {Error} Se o usuário não for encontrado
 * @example
 * const usuario = await buscarUsuario(42);
 * console.log(usuario.nome);
 */
async function buscarUsuario(id) {
  // implementação...
}

Gerando a documentação

npx jsdoc -c jsdoc.json

Isso cria uma pasta docs/ com HTML navegável. Para automatizar, adicione ao package.json:

{
  "scripts": {
    "docs": "jsdoc -c jsdoc.json",
    "docs:watch": "nodemon --watch src --exec 'npm run docs'"
  }
}

Documentação automática com TypeScript e ferramentas modernas

Usando TypeDoc

Para projetos TypeScript, TypeDoc é a ferramenta padrão:

npm install --save-dev typedoc

Configure no tsconfig.json:

{
  "typedocOptions": {
    "entryPoints": ["src/index.ts"],
    "out": "docs"
  }
}

Exemplo de código TypeScript com documentação:

/**
 * Interface que define as opções de configuração do sistema
 */
interface ConfiguracaoSistema {
  /** URL base da API */
  baseUrl: string;
  /** Timeout em milissegundos */
  timeout: number;
  /** Se deve usar cache */
  cache?: boolean;
}

/**
 * Inicializa o sistema com as configurações fornecidas
 * @param config - Configurações parciais (valores padrão são aplicados)
 * @returns Status da inicialização
 */
function inicializarSistema(config: Partial<ConfiguracaoSistema>): boolean {
  // implementação...
}

Execute:

npx typedoc

TypeDoc gera uma documentação interativa com busca, navegação por módulos e destaque de tipos.

Documentação de API REST com OpenAPI e Swagger

Para documentar APIs REST, a combinação swagger-jsdoc + swagger-ui-express é poderosa.

Instalação

npm install swagger-jsdoc swagger-ui-express

Configuração básica com Express

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API de Usuários',
      version: '1.0.0',
    },
  },
  apis: ['./src/routes/*.js'],
};

const swaggerSpec = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Documentando rotas com anotações JSDoc

/**
 * @openapi
 * /usuarios:
 *   get:
 *     summary: Lista todos os usuários
 *     tags: [Usuários]
 *     responses:
 *       200:
 *         description: Lista de usuários
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/Usuario'
 */
router.get('/usuarios', async (req, res) => {
  // implementação...
});

Acesse http://localhost:3000/api-docs para ver a interface interativa do Swagger.

Automatizando a geração no fluxo de desenvolvimento

Scripts no package.json

Configure scripts para geração automática:

{
  "scripts": {
    "build": "npm run build:ts && npm run docs",
    "build:ts": "tsc",
    "docs": "typedoc",
    "docs:api": "node scripts/gerar-swagger.js"
  }
}

Integração com Git hooks

Use husky para gerar documentação antes de commits:

npm install --save-dev husky
npx husky init

No arquivo .husky/pre-commit:

#!/bin/sh
npm run docs
git add docs/

Publicação automática

Configure GitHub Actions para publicar a documentação no GitHub Pages:

name: Deploy Docs
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run docs
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

Boas práticas e armadilhas comuns

  1. Documente contratos públicos, não implementações internas: foque em APIs, funções exportadas e interfaces. Funções internas raramente precisam de documentação extensa.

  2. Evite documentação genérica: @param {string} nome - O nome não agrega valor. Prefira @param {string} nome - Nome completo do usuário (mínimo 3 caracteres).

  3. Código legado sem tipos: use JSDoc progressivamente. Comece documentando as funções mais críticas e expanda gradualmente.

  4. Manutenção contínua vs revisão periódica: a geração automática resolve o problema de atualização, mas não substitui a necessidade de revisar se a documentação está clara e útil. Agende revisões trimestrais.

  5. Versionamento da documentação: mantenha a documentação junto com o código no mesmo repositório. Use tags do Git para versionar a documentação junto com o código.

A documentação automática transforma um processo manual e propenso a erros em um fluxo contínuo e confiável. Com as ferramentas certas e boas práticas, sua equipe terá documentação sempre atualizada, reduzindo o atrito na integração de novos membros e melhorando a experiência de quem consome suas APIs.

Referências