Documentação em TypeScript: como escrever código que fala por si só

Introdução: por que a documentação não é uma obrigação chata, mas um superpoder

Imagine: você volta ao seu projeto depois de seis meses. Abre o arquivo com a lógica de autenticação — e vê um mar de código em TypeScript. Os tipos existem, as interfaces estão definidas, mas o que esta função faz? Por que o parâmetro se chama opts e quais campos ele tem? Familiar?

Documentação em TypeScript não é apenas "comentários para marcar presença". É uma ferramenta que transforma seu código em uma história compreensível. Uma boa documentação economiza horas de depuração, acelera a integração de novos membros e torna sua API amigável. Neste artigo, vamos abordar as melhores práticas de documentação de projetos TypeScript: desde comentários básicos JSDoc até a geração avançada de documentação com TypeDoc. Vamos nessa!

1. JSDoc e TSDoc: a base da sua documentação

O TypeScript herdou do JavaScript o formato popular JSDoc, e então a comunidade desenvolveu o TSDoc — uma sintaxe padronizada para TypeScript. Se você escreve uma biblioteca ou API, o TSDoc é a sua escolha. Ele é mais rigoroso, integra-se melhor com editores e geradores de documentação.

Tags básicas do TSDoc

Aqui está o mínimo que todo desenvolvedor deve saber:

\n
• @param — descrição do parâmetro da função
\n
• @returns — o que a função retorna
\n
• @throws — quais exceções pode lançar
\n
• @example — exemplo de uso
\n
• @deprecated — marcação de código obsoleto
\n

/**\n * Calcula o desconto em um produto considerando um código promocional.\n * \n * @param price - Preço original do produto (deve ser maior que 0)\n * @param discountPercent - Percentual de desconto (de 0 a 100)\n * @param promoCode - Código promocional que pode aumentar o desconto\n * @returns Preço final após aplicar o desconto\n * @throws {Error} Se o preço ou percentual forem inválidos\n * \n * @example\n * // Exemplo: desconto de 20% em um produto de 1000 reais\n * const finalPrice = calculateDiscount(1000, 20, 'SUMMER');\n * console.log(finalPrice); // 800\n */\nfunction calculateDiscount(\n  price: number,\n  discountPercent: number,\n  promoCode?: string\n): number {\n  if (price <= 0 || discountPercent < 0 || discountPercent > 100) {\n    throw new Error('Parâmetros inválidos');\n  }\n  \n  let discount = discountPercent;\n  if (promoCode === 'SUMMER') {\n    discount += 10; // desconto adicional\n  }\n  \n  return price * (1 - discount / 100);\n}\n

Dica: Sempre descreva os casos limite. Se o parâmetro pode ser undefined, indique isso na descrição. Os tipos do TypeScript são bons, mas a linguagem humana adiciona contexto.

2. Documente tipos e interfaces

Uma das principais características do TypeScript é seu poderoso sistema de tipos. Mas mesmo o tipo mais rigoroso não explica o propósito de um campo. Documente as interfaces com tanto cuidado quanto as funções.

/**\n * Configuração para conexão com uma API externa de clima.\n */\ninterface WeatherApiConfig {\n  /** URL base da API (exemplo: https://api.weather.com) */\n  baseUrl: string;\n  \n  /** Chave de autenticação obtida do provedor */\n  apiKey: string;\n  \n  /** \n   * Número de segundos para aguardar resposta do servidor.\n   * Padrão: 5 segundos.\n   */\n  timeout?: number;\n  \n  /**\n   * Versão da API. Se não especificada, usa a última estável.\n   * @deprecated Use o campo `version` na URL\n   */\n  apiVersion?: string;\n}\n

Observe: para timeout, indicamos o valor padrão diretamente no comentário. Isso evita que o desenvolvedor precise consultar o código-fonte ou os testes.

3. Geração de documentação: transformando comentários em site

Escrever comentários é metade do trabalho. É preciso saber transformá-los em documentação acessível. Para TypeScript, a melhor ferramenta é o TypeDoc. Ele analisa seus comentários TSDoc