A prática de documentar o código é crucial, embora muitas vezes negligenciada, no desenvolvimento de software. Como profissional de desenvolvimento, você provavelmente está acostumado a criar código limpo e eficaz, mas pode ter menos experiência na elaboração de documentação de qualidade.
Uma documentação bem estruturada é valiosa para todos que interagem com seu código, seja sua equipe ou você mesmo no futuro. Ela esclarece as decisões de implementação e o uso de funções ou APIs.
Para desenvolvedores JavaScript, o JSDoc surge como uma ferramenta eficaz para iniciar a documentação do seu código.
O que é JSDoc?
A tarefa de documentar o código pode ser complexa e repetitiva. No entanto, cada vez mais pessoas reconhecem as vantagens de uma abordagem de “documentação como código”, e várias linguagens oferecem bibliotecas que auxiliam na automatização desse processo. Para uma documentação simples, clara e concisa, o JavaScript dispõe do JSDoc, análogo ao GoDoc da linguagem Go.
O JSDoc gera documentação através da interpretação de comentários específicos no código-fonte JavaScript, processando esses comentários e criando documentação personalizada. Posteriormente, disponibiliza essa documentação em formato HTML acessível.
Isso mantém a documentação integrada ao código, facilitando a atualização da documentação sempre que o código for modificado.
Configurando o JSDoc
Os criadores do JSDoc simplificaram a introdução e configuração do JSDoc em projetos JavaScript.
Para instalar o JSDoc localmente, execute:
npm install --save-dev jsdoc
Isso adicionará a biblioteca ao seu projeto como uma dependência de desenvolvimento.
Para utilizar o JSDoc, você empregará comentários com sintaxe especial dentro do código-fonte. Os comentários da documentação devem ser escritos entre os marcadores /** e */. Dentro deles, você pode detalhar variáveis, funções, parâmetros de funções e muito mais.
Por exemplo:
* Recupera um usuário pelo nome.
* @param {string} name - O nome do usuário
* @returns {string} Usuário
*/ function getUser(name) {
const User = name;
return User;
}
As tags @param e @returns são apenas duas das muitas palavras-chave especiais que o JSDoc reconhece para explicar seu código.
Para gerar a documentação deste código, utilize o comando npx jsdoc seguido do caminho do seu arquivo JavaScript.
Por exemplo:
npx jsdoc src/main.js
Caso tenha instalado o JSDoc globalmente, pode omitir o sinalizador npx e executar:
Esse comando criará uma pasta de saída na raiz do seu projeto. Dentro dela, você encontrará arquivos HTML que representam as páginas da sua documentação.
Você pode visualizar a documentação iniciando um servidor web local para hospedá-la ou simplesmente abrindo o arquivo out/index.html em um navegador. Abaixo está um exemplo de como uma página de documentação se apresenta por padrão:
Configurando a saída do JSDoc
Você pode criar um arquivo de configuração para modificar o comportamento padrão do JSDoc.
Para isso, crie um arquivo conf.js e exporte um módulo JavaScript dentro deste arquivo.
Por exemplo:
module.exports = {
source: {
includePattern: ".+\\.js(doc|x)?$",
excludePattern: ["node_modules"],
},
recurseDepth: 5,
sourceType: "module",
opts: {
template: "path/to/template",
destination: "./docs/",
recurse: true,
},
};
Dentro do arquivo de configuração, existem várias opções de configuração JSDoc. A opção de modelo permite personalizar a aparência da documentação. A comunidade JSDoc disponibiliza diversos modelos prontos para uso. O pacote também oferece a possibilidade de criar seus próprios modelos personalizados.
Para alterar o local onde a documentação gerada será armazenada, defina a opção de configuração de destino como um diretório. O exemplo acima especifica uma pasta docs na raiz do projeto.
Utilize este comando para executar o JSDoc com um arquivo de configuração:
jsdoc -c /path/to/conf.js
Para facilitar a execução deste comando, adicione-o como uma entrada de script dentro do seu arquivo package.json:
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Agora você pode executar o script npm a partir de um terminal.
Um exemplo de documentação gerada com JSDoc
A seguir, apresentamos uma biblioteca aritmética simplificada com funções de adição e subtração.
Este é um exemplo de código JavaScript bem documentado:
* Uma biblioteca para realizar operações aritméticas básicas.
* @module arithmetic
*/ module.exports = { * Adiciona dois números.
* @param {number} a - O primeiro número.
* @param {number} b - O segundo número.
* @return {number} A soma dos dois números.
* @throws {TypeError} Se algum dos argumentos não for um número.
* * @example
* const arithmetic = require('arithmetic');
* const sum = arithmetic.add(5, 10);
* console.log(sum);
*/ add: function(a, b) { if (typeof a !== 'number' || typeof b !== 'number') { throw new TypeError('Ambos os argumentos devem ser números.'); } return a + b; }, * Subtrai o segundo número do primeiro.
* @param {number} a - O número do qual subtrair.
* @param {number} b - O número a ser subtraído.
* @return {number} O resultado da subtração.
* @throws {TypeError} Se algum dos argumentos não for um número.
* * @example
* const arithmetic = require('arithmetic');
* const difference = arithmetic.subtract(10, 5);
* console.log(difference);
*/ subtract: function(a, b) { if (typeof a !== 'number' || typeof b !== 'number') { throw new TypeError('Ambos os argumentos devem ser números.'); } return a - b; } };
Os comentários JSDoc oferecem uma descrição clara e abrangente da biblioteca e seus métodos, incluindo:
- Uma descrição da biblioteca e seu propósito.
- Os parâmetros de cada método, incluindo seu tipo e uma breve descrição.
- O valor e tipo de retorno de cada método.
- Os erros que cada método pode gerar e as condições que os causam.
- Um exemplo de como usar cada método.
Os comentários também incluem a tag @module para indicar que este arquivo é um módulo e a tag @example para apresentar um exemplo de código para cada método.
Documentando o código do desenvolvedor da maneira correta
Como demonstrado, o JSDoc é uma ferramenta muito útil para iniciar a documentação de código JavaScript. Sua fácil integração permite gerar documentação detalhada e rápida enquanto você escreve seu código, mantendo e atualizando a documentação diretamente no seu espaço de trabalho.
Entretanto, apesar da utilidade da automação do JSDoc, algumas diretrizes devem ser seguidas para criar uma documentação de qualidade.