Como documentar código JavaScript usando JSDoc

A documentação adequada do código é um aspecto importante, mas muitas vezes esquecido, do desenvolvimento de software. Como desenvolvedor, você estará acostumado a escrever código limpo e eficiente, mas poderá ter menos experiência em escrever boa documentação.

Uma boa documentação é útil para qualquer pessoa que trabalhe com seu código, sejam outros membros de sua equipe ou você mesmo, posteriormente. Pode explicar por que você implementou algo de uma maneira específica ou como usar uma função ou API específica.

Para desenvolvedores JavaScript, JSDoc é uma boa maneira de começar a documentar seu código.

O que é JSDoc?

Documentar o código pode ser complexo e tedioso. No entanto, mais pessoas estão reconhecendo os benefícios da uma abordagem de “documentos como código”e muitas linguagens possuem bibliotecas que ajudam a automatizar o processo. Para documentação simples, clara e concisa. Assim como o

JSDoc gera documentação interpretando comentários especiais em seu código-fonte JavaScript, processando esses comentários e produzindo documentação personalizada. Em seguida, disponibiliza esta documentação em um formato HTML acessível.

Isso mantém a documentação dentro do código, portanto, quando você atualizar seu código, será fácil atualizar a documentação.

Configurando JSDoc

Os criadores do JSDoc facilitaram a introdução e a configuração do JSDoc em seu projeto JavaScript.

Para instalar o JSDoc localmente, execute:

npm install --save-dev jsdoc

Isso instalará a biblioteca em seu projeto como uma dependência de desenvolvimento.

Para usar JSDoc, você usará comentários de sintaxe especiais dentro de seu código-fonte. Você escreverá todos os comentários da sua documentação dentro /** e */ marcadores. Dentro deles, você pode descrever variáveis ​​definidas, funções, parâmetros de função e muito mais.

Por exemplo:

/**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */
functiongetUser(name) {
const User = name;
return User;
}

O @param e @devoluções tags são duas das muitas palavras-chave especiais que o JSDoc suporta para explicar seu código.

Para gerar a documentação deste código, execute jsdoc npx seguido pelo caminho para o seu arquivo JavaScript.

Por exemplo:

npx jsdoc src/main.js

jsdoc path/to/file.js

Este comando irá gerar um fora pasta na raiz do seu projeto. Dentro da pasta você encontrará arquivos HTML representando as páginas da sua documentação.

Você pode visualizar a documentação em configurando um servidor web local para hospedá-lo, ou simplesmente abrindo o arquivo out/index.html dentro de um navegador. Aqui está um exemplo de como será a aparência de uma página de documentação por padrão:

Configurando a saída JSDoc

Você pode criar um arquivo de configuração para alterar o comportamento padrão do JSDoc.

Para fazer isso, crie um conf.js arquivo 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ários Configuração JSDoc opções. O modelo opção permite usar um modelo para personalizar a aparência da documentação. A comunidade JSDoc oferece muitos modelos que você pode usar. O pacote também permite que você crie seus próprios modelos personalizados.

Para alterar o local da documentação gerada, defina a opção destino opção de configuração para um diretório. O exemplo acima especifica um documentos pasta na raiz do projeto.

Use este comando para executar JSDoc com um arquivo de configuração:

jsdoc -c /path/to/conf.js

Para facilitar a execução deste comando, adicione-o como um roteiros entrada dentro do seu pacote.json arquivo:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

Agora você pode execute o comando de script npm dentro de um terminal.

Um exemplo de documentação gerada com JSDoc

Abaixo está uma biblioteca aritmética simples com adicionar e subtrair métodos.

Este é um exemplo de código JavaScript bem documentado:

/**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
/**
 * Adds two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @return {number} The sum of the two numbers.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const sum = arithmetic.add(5, 10);
 * console.log(sum); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a + b;
 },
/**
 * Subtracts the second number from the first number.
 * @param {number} a - The number to subtract from.
 * @param {number} b - The number to subtract.
 * @return {number} The result of the subtraction.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const difference = arithmetic.subtract(10, 5);
 * console.log(difference); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

Os comentários JSDoc fornecem uma descrição clara e abrangente da biblioteca e seus métodos, incluindo:

• Uma descrição da biblioteca e sua finalidade.
• Parâmetros de cada método, incluindo seu tipo e uma breve descrição.
• O valor e o tipo que cada método retorna.
• 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 @módulo tag para indicar que este arquivo é um módulo e o @exemplo tag para fornecer um exemplo de código para cada método.

Documentando o código do desenvolvedor da maneira certa

Como você pode ver, JSDoc é uma ferramenta muito útil para você começar a documentar o código JavaScript. Com sua fácil integração, você pode gerar documentação rápida e detalhada enquanto escreve seu código. Você também pode manter e atualizar a documentação diretamente em seu espaço de trabalho.

No entanto, por mais útil que seja a automação do JSDoc, você ainda deve seguir certas diretrizes para poder criar documentação de qualidade.