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.
últimas postagens
O que é JSDoc?
Documentar o código pode ser complexo e tedioso. No entanto, mais pessoas estão reconhecendo os benefícios de uma abordagem “documentos como código”, e muitas linguagens possuem bibliotecas que ajudam a automatizar o processo. Para documentação simples, clara e concisa. Assim como a linguagem Go possui GoDoc para automatizar a documentação do código, o JavaScript possui JSDoc.
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 dos marcadores /** e */. 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
*/function getUser(name) {
const User = name;
return User;
}
As tags @param e @returns 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 npx jsdoc seguido do caminho para o seu arquivo JavaScript.
Por exemplo:
npx jsdoc src/main.js
Se você instalou o JSDoc globalmente, poderá omitir o sinalizador npx e executar:
Este comando irá gerar uma pasta de saída 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 configurando um servidor web local para hospedá-la 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 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ários Configuração JSDoc opções. A opção de modelo 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 de configuração de destino como um diretório. O exemplo acima especifica uma pasta docs 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 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 comando de script npm dentro de um terminal.
Um exemplo de documentação gerada com JSDoc
Abaixo está uma biblioteca aritmética simples com métodos de adição e subtração.
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);
*/
add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('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);
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}return a - b;
}
};
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 a tag @module para indicar que este arquivo é um módulo e a tag @example 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.