Escrevendo documentação para projetos TypeScript: do A ao Z

Introdução: por que a documentação é necessária em projetos TypeScript

Documentação de qualidade não é apenas um bônus agradável, mas um elemento criticamente importante de qualquer projeto TypeScript profissional. Ela serve como uma ponte entre desenvolvedores, facilita a integração de novos membros da equipe e ajuda a evitar erros ao usar a API. O TypeScript, com seu poderoso sistema de tipos, oferece oportunidades únicas para gerar documentação precisa e autodocumentável. Neste artigo, abordaremos o processo completo: desde escrever comentários no código até publicar a documentação pronta.

Fundamentos: JSDoc e anotações para TypeScript

O TypeScript suporta a sintaxe JSDoc, permitindo adicionar comentários estruturados diretamente no código. Esta é a base para criar documentação compreensível tanto para humanos quanto para ferramentas.

Tags básicas do JSDoc

Vamos começar com um exemplo simples de uma função que soma dois números:

/**\n * Soma dois números.\n * @param a - Primeiro número a ser somado.\n * @param b - Segundo número a ser somado.\n * @returns A soma dos dois números.\n */\nfunction add(a: number, b: number): number {\n    return a + b;\n}

Tags principais:

\n
• @param — descreve um argumento da função. Recomenda-se especificar o tipo e a finalidade.
\n
• @returns — descreve o valor de retorno.
\n
• @throws — indica quais exceções a função pode lançar.
\n
• @example — mostra um exemplo de uso.
\n

Documentando tipos complexos

Para interfaces e tipos, use @property ou descreva os campos dentro do bloco:

interface UserConfig {\n    /** Nome do usuário */\n    name: string;\n    /** Idade do usuário (opcional) */\n    age?: number;\n    /** Papel no sistema */\n    role: 'admin' | 'user';\n}\n\n/**\n * Cria uma configuração de usuário.\n * @param config - Objeto com as configurações do usuário.\n * @returns Objeto de configuração.\n */\nfunction createUser(config: UserConfig): UserConfig {\n    return config;\n}

Use @template para genéricos:

/**\n * Invólucro para armazenar um valor.\n * @template T - Tipo do valor armazenado.\n */\nclass Box<T> {\n    /** Valor armazenado */\n    value: T;\n    constructor(value: T) {\n        this.value = value;\n    }\n}

Ferramentas para geração de documentação: TypeDoc

TypeDoc é a principal ferramenta para geração automática de documentação a partir de anotações JSDoc em TypeScript. Ele cria um site HTML estático com navegação conveniente.

Instalação e configuração

Instale o TypeDoc como uma dependência de desenvolvimento:

npm install --save-dev typedoc

Crie um arquivo de configuração typedoc.json na raiz do projeto:

{\n  "entryPoints": ["src/index.ts"],\n  "out": "docs",\n  "theme": "default",\n  "excludePrivate": true,\n  "excludeProtected": false,\n  "includeVersion": true,\n  "categorizeByGroup": true\n}

Parâmetros de configuração:

\n
• entryPoints — ponto de entrada do seu projeto (geralmente o arquivo de exportação principal).
\n
• out — pasta onde a documentação será gerada.
\n
• excludePrivate — ocultar membros privados das classes.
\n
• includeVersion — adicionar a versão do projeto à documentação.
\n

Executando a geração

Adicione um script ao package.json:

{\n  "scripts": {\n    "docs:generate": "typedoc"\n  }\n}

Execute o comando:

npm run docs:generate

Depois disso, um site estático aparecerá na pasta docs. Abra docs/index.html no navegador.

Melhores práticas para escrever documentação

Para que a documentação seja útil, siga algumas regras.

1. Escreva comentários