TypeScript Documentation: JSDoc útil sem comentar o óbvio

ANÁLISE EDITORIAL

Comentários demais escondem o código; comentários de menos obrigam cada pessoa a redescobrir contratos e exceções. A TypeScript Documentation orienta um agente a revisar JSDoc, explicar APIs exportadas, tratar genéricos e limpar comentários que apenas repetem a implementação.

O que esta Skill faz

A Skill cria um roteiro para auditar documentação em JavaScript e TypeScript. Ela procura funções, tipos, interfaces, classes e constantes que precisam de contexto, verifica tags como @param, @returns, @template, @throws e @example, e separa documentação de API de comentários sobre a implementação.

Também revisa marcadores como TODO, FIXME, HACK, NOTE e PERF. O objetivo não é aumentar a quantidade de texto, mas deixar explícitos propósito, condições, unidades, exceções e decisões que não aparecem na assinatura.

Para quem serve

É útil para equipes que mantêm bibliotecas TypeScript, SDKs, pacotes npm, APIs internas, componentes compartilhados ou aplicações com muitas funções exportadas. Também ajuda em uma revisão pontual antes de publicar uma nova versão, abrir uma API para outro time ou transferir a manutenção de um módulo.

Ela não substitui a Code Review and Quality, que cobre defeitos e estrutura de código, nem a Simple English, voltada à clareza do texto. Aqui, o escopo é o contrato explicado ao redor do código e a qualidade dos comentários.

Origem, versão e baixa adoção

A origem auditada é a pasta skills/accelint-ts-documentation, no commit 3336c8eda617308f1df327c83d9f6601eb2b79de. O frontmatter declara versão 1.1.0 e licença Apache-2.0.

O README do repositório lista a Skill entre as 23 pastas mantidas e documenta a instalação pelo Skills CLI. Na consulta, o projeto não tinha adoção suficiente para a regra geral de mil estrelas. A curadoria aceitou a exceção porque a organização mantenedora, a documentação, o commit e a licença são verificáveis. Isso não transforma a Skill em padrão oficial de TypeScript ou JSDoc.

Compatibilidade e pré-requisitos

Os arquivos seguem o formato de Agent Skills em Markdown. Um cliente compatível precisa conseguir carregar o SKILL.md e, quando necessário, as duas referências. O pacote não instala TypeScript, compilador, linter, TypeDoc ou JSDoc.

Para uso real, tenha um repositório JavaScript ou TypeScript, uma política de documentação definida e um modo de verificar o diff. Se a tarefa envolver compilação, execute os comandos já adotados pelo projeto. A documentação oficial do TypeScript sobre JSDoc deve prevalecer sobre exemplos genéricos da Skill quando houver dúvida de sintaxe ou suporte.

Instalação com origem conferível

O mantenedor recomenda instalar pelo Skills CLI no escopo do projeto:

npx skills add gohypergiant/agent-skills --skill accelint-ts-documentation

npx consulta a rede, executa um pacote e grava arquivos. Faça o primeiro teste em uma cópia ou projeto descartável, confira o destino e revise tudo o que foi criado. Para reproduzir esta curadoria, use o commit fixado e compare o SKILL.md auditado com o arquivo instalado.

Configuração antes do primeiro uso

Defina primeiro o que é API pública no seu projeto. Uma função exportada por um arquivo não é necessariamente parte do contrato público do pacote. Verifique package.json, campos exports, arquivos de declaração, documentação existente e convenções do time.

Depois, limite o trabalho por pasta e tipo de mudança. Um bom escopo inicial é: “audite somente src/public, não altere assinaturas, não renomeie símbolos, não remova diretivas de ferramentas e entregue primeiro um relatório”. Isso evita que uma tarefa de documentação vire refatoração silenciosa.

Primeiro uso seguro

Comece em modo de relatório, sem editar arquivos:

Audite a documentação de src/public em modo somente leitura.
Considere pública apenas a API exportada por package.json.
Liste achados com arquivo e linha.
Separe ausência de JSDoc, tag incompleta, comentário obsoleto e diretiva de ferramenta.
Não altere código, comentários, configuração ou Git.

Revise a lista antes de autorizar correções. Em uma segunda etapa, selecione poucos achados, peça um diff e execute testes ou checagens do próprio projeto. A Skill inclui um template de relatório, mas quantidade de achados não mede qualidade da documentação.

Separar API pública de código interno

A parte mais útil da Skill é o critério em duas camadas. Para consumidores externos, descrições, parâmetros, retorno, erros e exemplos têm valor porque o leitor não deveria abrir a implementação para descobrir o contrato. Para código interno, o nome e os tipos podem explicar o comportamento suficiente.

Documentar toda função interna tende a produzir texto que envelhece junto com uma implementação de alta mudança. Prefira comentários quando existe uma razão não óbvia, uma unidade, uma restrição, um efeito colateral, uma compatibilidade delicada ou uma decisão que a assinatura não expressa.

Tratar JSDoc como contrato, não decoração

Um @param útil explica significado, unidade, limite ou condição. Repetir “o identificador do usuário” para um parâmetro chamado userId raramente ajuda. Já dizer que o identificador é externo, case-sensitive e não pode ser reutilizado muda a forma de usar a função.

O mesmo vale para @returns. Descreva estados possíveis e diferenças relevantes, sem recontar o tipo. Use @throws somente quando a função realmente pode lançar e indique a condição. Exemplos precisam ser pequenos, plausíveis e compatíveis com a API atual.

Documentar genéricos e objetos

A Skill pede @template para explicar parâmetros genéricos. Isso é útil quando T representa mais do que “qualquer tipo”, por exemplo o registro original preservado em uma transformação ou o formato exigido por um adaptador.

Para parâmetros de objeto, a referência recomenda notação com pontos, como @param config.timeout. Antes de aplicar a regra mecanicamente, compare com a ferramenta que gera sua documentação e com os tipos TypeScript existentes. Em alguns projetos, a interface e suas propriedades documentadas oferecem uma fonte mais estável do que repetir cada campo em todas as funções.

Preservar diretivas de ferramentas

Comentários como eslint-disable-next-line, prettier-ignore, biome-ignore e @ts-expect-error não são prosa comum. Eles têm sintaxe e efeito próprios. Remover, mover ou reformatar uma diretiva pode alterar lint, formatação ou compilação.

A Skill manda preservá-los. Ainda assim, uma auditoria deve verificar se cada supressão tem justificativa e continua necessária. Essa análise precisa ser separada da limpeza de comentários, com teste específico antes e depois.

Usar TODO e FIXME com contexto

Marcadores vagos, como TODO: corrigir, não registram condição de conclusão, impacto nem responsável. A referência propõe adicionar contexto, autoria e, quando existir, vínculo com uma issue. Essa convenção deve seguir a política do repositório, não o gosto do agente.

Também não trate todo comentário sem marcador como dispensável. Explicações de regra de negócio, compatibilidade, segurança e comportamento de terceiros podem ser essenciais. O critério é preservar o motivo que não pode ser inferido facilmente do código.

Uma inconsistência que exige julgamento

Os arquivos não são perfeitamente alinhados. O references/jsdoc.md afirma que todas as funções, aliases, interfaces, constantes e classes, inclusive internas, devem receber JSDoc. Já o SKILL.md usa um critério mais seletivo para código interno e diz para documentar apenas o que não é autoexplicativo.

A curadoria recomenda seguir o segundo critério, depois de confirmar a convenção do projeto. Se o repositório exige cobertura documental ampla por política ou geração automática, aplique essa regra explícita. Fora desse caso, evite criar centenas de comentários redundantes só para satisfazer uma frase da referência.

Resultado esperado

Um uso bem delimitado entrega um relatório com arquivo, linha, categoria e justificativa. Depois da aprovação, o diff deve melhorar contratos públicos, registrar exceções e remover ruído sem alterar comportamento, assinatura, tipos, exports ou diretivas.

O resultado não é “100% documentado”. É uma base em que o leitor entende como chamar uma API, quais limites respeitar, o que pode falhar e por que uma decisão incomum existe. Compilação, testes e revisão continuam sendo evidências separadas.

Permissões e riscos

O ZIP é só texto e não executa nada. O uso funcional, porém, pode conceder leitura ampla do código e escrita em muitos arquivos. Código privado, chaves acidentais, endpoints internos, regras de negócio e comentários de incidentes podem entrar no contexto do agente.

Minimize a pasta, exclua segredos, comece somente com leitura e aprove cada lote de escrita. Não autorize publicação npm, commit, push, alteração de versão ou modificação de API como parte implícita da auditoria. Comentários também podem vazar detalhes internos quando um pacote é público.

Erros comuns e como corrigir

• Documentar o óbvio: troque repetição por contexto, unidade, condição ou remova o comentário.
• Inventar erro: confirme caminhos reais antes de adicionar @throws.
• Exemplo que não compila: teste o trecho no ambiente e na versão do projeto.
• Apagar diretiva: separe diretivas de ferramentas dos comentários editoriais.
• Tratar export como API pública: valide o mapa de exports e a documentação do pacote.
• Editar tudo de uma vez: faça lotes pequenos, revise o diff e rode as verificações existentes.
• Copiar segredo para exemplo: use dados sintéticos e placeholders inequívocos.

Versão, licença e pacote auditado

A Skill declara versão 1.1.0. O commit auditado é 3336c8eda617308f1df327c83d9f6601eb2b79de. A licença Apache-2.0 da raiz permite redistribuição quando suas condições são preservadas.

O pacote local contém oito arquivos textuais: SKILL.md, README.md, AGENTS.md, duas referências Markdown, o template de relatório, LICENSE e ORIGEM.md. Tamanho: 22.899 bytes. SHA-256: 5497400923bc395ce60057fbcf0dfd6cfe211364045632d421b8aad2698c4d10.

Limites do pacote local

O ZIP não inclui o restante das 23 Skills, a aplicação de documentação do repositório, scripts de symlink, dependências, Node.js, npm, TypeScript, JSDoc, TypeDoc, código do leitor, relatórios, memória ou credenciais.

Ele é um espelho documental do commit fixado, não um instalador e não uma atualização automática. O ORIGEM.md registra os arquivos, o caminho, os números observados e a ressalva editorial sobre a inconsistência interna.

Checklist antes de executar

• Defina o que é API pública e qual pasta será lida.
• Comece em modo de relatório, sem escrever.
• Confirme a convenção de JSDoc, linter e gerador de documentação.
• Preserve diretivas e comentários de regra de negócio.
• Use exemplos sintéticos e não copie segredos.
• Aprove poucos arquivos por lote e revise o diff.
• Rode as checagens existentes antes de aceitar a mudança.

Fontes oficiais consultadas

• Pasta da TypeScript Documentation no commit auditado
• SKILL.md original no GitHub
• README e instalação do repositório
• Licença Apache-2.0 preservada
• TypeScript: tipos suportados em JSDoc
• TypeScript: padrões JSDoc não suportados
• Especificação pública de Agent Skills