Documentação com TypeDoc

1. Introdução ao TypeDoc e sua Integração com TypeScript

TypeDoc é uma ferramenta de geração de documentação projetada especificamente para projetos TypeScript. Diferentemente do JSDoc, que foi criado para JavaScript e adaptado posteriormente, o TypeDoc entende nativamente o sistema de tipos do TypeScript, incluindo genéricos, tipos condicionais, utilitários de tipo e módulos ES.

Enquanto o JSDoc exige anotações manuais para tipos complexos, o TypeDoc infere automaticamente a maioria das informações a partir do código-fonte. Já o Docusaurus é um gerador de sites de documentação mais geral, que pode ser combinado com TypeDoc para criar portais completos, mas não substitui a geração automática baseada em código.

Para instalar e configurar:

npm install typedoc --save-dev

Crie um arquivo typedoc.json na raiz do projeto:

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

Execute com:

npx typedoc

2. Anatomia dos Comentários TypeDoc

A documentação utiliza blocos de comentário /** ... */. Tags especiais controlam o que é gerado:

/**
 * Calcula o valor total com impostos aplicados.
 *
 * @param valor - Valor base do produto em reais
 * @param aliquota - Percentual do imposto (ex: 0.18 para 18%)
 * @returns O valor final com imposto incluso
 * @throws {RangeError} Se a aliquota for negativa
 *
 * @example
 * ```typescript
 * const total = calcularImposto(100, 0.18);
 * console.log(total); // 118
 * ```
 */
function calcularImposto(valor: number, aliquota: number): number {
  if (aliquota < 0) throw new RangeError("Alíquota não pode ser negativa");
  return valor * (1 + aliquota);
}

Tags avançadas incluem:

/**
 * Representa uma entidade persistente no banco de dados.
 *
 * @category Modelos
 * @group Entidades
 * @deprecated Use {@link EntidadeBase} em novos projetos
 */
interface Entidade {
  id: string;
}

3. Documentando Tipos e Interfaces Complexas

Para tipos genéricos, use @typeParam para documentar o parâmetro de tipo:

/**
 * Cache tipado com suporte a expiração.
 *
 * @typeParam T - Tipo dos valores armazenados no cache
 * @typeParam K - Tipo da chave (padrão: string)
 */
class Cache<T, K extends string = string> {
  private dados = new Map<K, T>();

  /**
   * @param chave - Identificador único
   * @param valor - Dado a ser armazenado
   * @param ttlMs - Tempo de vida em milissegundos
   */
  set(chave: K, valor: T, ttlMs: number): void {
    // implementação
  }
}

Propriedades de objetos literais são documentadas com @property:

/**
 * Configuração para conexão com banco de dados.
 *
 * @property host - Endereço do servidor
 * @property porta - Número da porta (padrão: 5432)
 * @property credenciais - Objeto com usuário e senha
 */
type ConfigDB = {
  host: string;
  porta?: number;
  credenciais: { usuario: string; senha: string };
};

Referências cruzadas com @link e @see:

/**
 * Processa um pedido e atualiza o estoque.
 *
 * @see {@link Estoque.atualizar} para detalhes da atualização
 * @see [Documentação de Pedidos](https://docs.exemplo.com/pedidos)
 *
 * @link https://api.exemplo.com/pedidos
 */
function processarPedido(pedido: Pedido): Resultado {
  // implementação
}

4. Configuração e Personalização do TypeDoc

O arquivo typedoc.json oferece diversas opções de customização:

{
  "entryPoints": ["src/index.ts", "src/componentes/index.ts"],
  "out": "docs",
  "tsconfig": "tsconfig.json",
  "excludePrivate": true,
  "excludeProtected": false,
  "includeVersion": true,
  "categorizeByGroup": true,
  "defaultCategory": "Geral",
  "plugin": [
    "typedoc-plugin-markdown",
    "typedoc-plugin-missing-exports"
  ]
}

Plugins oficiais importantes:

  • typedoc-plugin-markdown: Gera documentação em formato Markdown em vez de HTML
  • typedoc-plugin-missing-exports: Adiciona símbolos não exportados à documentação

Para temas personalizados, você pode usar temas de terceiros como typedoc-theme-dark ou criar o seu próprio estendendo o tema padrão.

5. Geração de Documentação para Monorepos

Em monorepos com múltiplos pacotes, configure diferentes entry points:

{
  "entryPointStrategy": "packages",
  "entryPoints": ["packages/*"],
  "out": "docs"
}

Use @packageDocumentation para documentar cada pacote individualmente:

/**
 * @packageDocumentation
 * Módulo de autenticação do sistema.
 *
 * Este pacote fornece funcionalidades de login, registro e
 * gerenciamento de sessões usando JWT.
 */

Para integração com Turborepo, configure scripts em cada pacote:

// packages/auth/package.json
{
  "scripts": {
    "typedoc": "typedoc --options typedoc.json"
  }
}

E no turbo.json:

{
  "pipeline": {
    "typedoc": {
      "dependsOn": ["^build"],
      "outputs": ["docs/**"]
    }
  }
}

Para geração consolidada, crie um script na raiz:

turbo run typedoc --parallel
npx typedoc --entryPointStrategy packages --entryPoints packages/*

6. Validação e Qualidade da Documentação

TypeDoc pode validar a completude da documentação durante a geração:

npx typedoc --validation

Configure regras específicas no typedoc.json:

{
  "validation": {
    "notDocumented": true,
    "invalidLink": true,
    "notExported": false
  },
  "treatWarningsAsErrors": true,
  "intentionallyNotExported": [
    "InternalHelper"
  ]
}

Isso faz com que símbolos públicos não documentados gerem erros, garantindo que toda API pública tenha documentação.

Integração com CI/CD (exemplo GitHub Actions):

- name: Verificar documentação
  run: npx typedoc --validation --treatWarningsAsErrors

Se a documentação estiver incompleta, o pipeline falha, impedindo deploys com documentação insuficiente.

7. Publicação e Versionamento da Documentação

Para gerar um site estático e publicar no GitHub Pages:

npx typedoc
# Os arquivos HTML serão gerados na pasta "docs"

Configure o GitHub Pages para servir a partir da branch gh-pages ou da pasta docs na branch principal.

Para versionamento com tags Git:

git tag v1.0.0
npx typedoc --gitRevision v1.0.0

Isso adiciona links para o código-fonte na versão correta.

Automação completa com GitHub Actions:

name: Publicar Documentação

on:
  release:
    types: [published]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx typedoc --gitRevision ${{ github.ref_name }}
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

Este workflow gera e publica automaticamente a documentação sempre que uma nova release é criada, com links apontando para o código daquela versão específica.

TypeDoc transforma seu código TypeScript em documentação rica e navegável, reduzindo drasticamente o esforço manual de documentação enquanto mantém a precisão técnica. Combinado com validação em CI/CD e publicação automatizada, ele se torna uma peça fundamental para manter projetos TypeScript bem documentados e fáceis de usar.

Referências