Como documentar código JavaScript usando JSDoc
A documentação adequada do código é um aspeto importante, mas muitas vezes negligenciado, do desenvolvimento de software. Como desenvolvedor, você está acostumado a escrever código limpo e eficiente, mas pode ser menos experiente em escrever uma boa documentação.
A documentação eficaz serve como um recurso inestimável para todos os indivíduos envolvidos em esforços colaborativos envolvendo sua base de código, incluindo iterações presentes e futuras do seu próprio eu. Ao fornecer esclarecimentos sobre as escolhas de design e oferecer orientação sobre a utilização de funções específicas ou APIs, promove uma maior compreensão e eficiência entre os utilizadores.
Para os proficientes em programação JavaScript, a utilização do JSDoc apresenta um excelente meio de iniciar o processo de documentação para a sua base de código.
O que é o JSDoc?
A adoção de uma estratégia “docs-as-code” tem-se tornado cada vez mais popular, com várias linguagens de programação a fornecerem bibliotecas dedicadas para simplificar este processo. Estas ferramentas permitem aos programadores gerar documentação abrangente e sucinta sem esforço. A título de exemplo, a linguagem de programação Go oferece o GoDoc para a geração automática de documentação com base em anotações de código, enquanto o JavaScript conta com o JSDoc para fins semelhantes no seu ecossistema.
Utilizando comentários especiais incorporados no código-fonte JavaScript, o JSDoc extrai e processa eficazmente essas anotações para gerar documentação personalizada. Esta documentação é posteriormente formatada num formato HTML de fácil utilização para uma acessibilidade conveniente.
Ao integrar a documentação diretamente no código-fonte, esta abordagem facilita um processo contínuo de atualização do código e da documentação correspondente sempre que são feitas modificações no primeiro.
Configurar o JSDoc
Os criadores do JSDoc simplificaram o processo para iniciar e integrar o JSDoc num projeto JavaScript, tornando-o acessível e fácil de utilizar desde o início.
Para instalar o JSDoc localmente, execute:
npm install --save-dev jsdoc
Instalar a biblioteca como uma dependência de desenvolvimento no seu projeto implica incorporá-la na infraestrutura existente do seu projeto, permitindo-lhe utilizar as suas características e funcionalidades conforme necessário.
Como escrever comentários JSDoc
Para utilizar o JSDoc, é necessário incorporar uma sintaxe de comentários específica diretamente no seu código-fonte.Todas as observações sobre a documentação devem ser colocadas dentro das etiquetas / e */ / , que permitem descrever em pormenor um vasto leque de elementos, tais como variáveis definidas, funções, parâmetros de funções e outras informações relevantes.
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;
}
JSDoc é uma ferramenta de documentação para JavaScript que utiliza várias palavras-chave especializadas, incluindo “@param” e “@returns”, para fornecer clareza em relação ao código. Essas palavras-chave específicas servem como anotações para parâmetros de função e valores de retorno, respetivamente, permitindo que os desenvolvedores entendam melhor como seu código deve ser usado e quais resultados podem ser esperados dele.
Para criar um documento abrangente que descreva a funcionalidade deste script, execute o comando “npx jsdoc” seguido do caminho especificado que conduz ao seu ficheiro JavaScript.
Por exemplo:
npx jsdoc src/main.js
Se tiver instalado o JSDoc como um pacote global, pode prescindir da utilização do comando “npx” executando simplesmente:
jsdoc path/to/file.js
A execução desta instrução resultará na criação de um diretório intitulado “out” dentro do diretório principal do seu projeto. Dentro desse diretório, descobrirá documentos HTML que incorporam o conteúdo da sua documentação.
Para aceder à documentação, tem duas opções disponíveis. A primeira envolve a configuração de um servidor Web local para servir de plataforma de alojamento para os ficheiros de documentação. Em alternativa, pode optar por abrir o conteúdo do ficheiro out/index.html no seu browser preferido para ver a documentação diretamente. Tenha em atenção que o aspeto predefinido de uma página de documentação é o seguinte:
Configurar a saída do JSDoc
Tem a opção de utilizar um ficheiro de configuração personalizado para modificar a funcionalidade padrão do JSDoc.
Para atingir este objetivo, é necessário estabelecer um ficheiro de configuração referido como “conf.js”. Neste ficheiro, deve exportar-se um módulo JavaScript que sirva o objetivo pretendido.
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 ficheiro de configuração existem várias opções de configuração do JSDoc . A opção de modelo permite-lhe utilizar um modelo para personalizar o aspeto da documentação. A comunidade do JSDoc fornece muitos modelos que pode utilizar. O pacote também permite que você crie seus próprios modelos personalizados.
Para transferir a documentação produzida automaticamente, é necessário designar um diretório específico como destino, ajustando a definição de configuração denominada “destino”. Como demonstrado anteriormente, a especificação de uma pasta “docs” designada, situada na área de armazenamento principal do projeto, permite atingir eficazmente este objetivo.
Execute a seguinte diretiva para operar o JSDoc utilizando um ficheiro de configuração:
jsdoc -c /path/to/conf.js
Para simplificar a execução deste comando, inclua-o como uma entrada “scripts” no seu ficheiro “package.json”. Isto permitirá a execução conveniente do comando a partir de qualquer lugar no diretório do seu projeto, executando “npm run [nome do script]”.
"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
},
Pode-se agora executar o comando npm script num ambiente de terminal, permitindo a execução dos comandos de script predefinidos associados ao Gestor de Pacotes Node.
Um exemplo de documentação gerada com JSDoc
Abaixo está uma biblioteca de aritmética elementar com métodos de adição e subtração.
Este exemplo demonstra uma implementação concisa e bem estruturada do JavaScript, caracterizada pela sua documentação clara que facilita a compreensão e a manutenção.
/**
* 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') {
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); // 5
*/
subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Both arguments must be numbers.');
}
return a - b;
}
// ... other methods ...
};
Os comentários do JSDoc oferecem uma descrição detalhada e abrangente da biblioteca e de suas funcionalidades, que englobam:
A biblioteca serve de repositório de várias obras literárias, proporcionando aos utentes uma vasta coleção de livros que satisfazem as suas necessidades intelectuais. O seu principal objetivo é facilitar o acesso à informação e ao conhecimento, permitindo aos indivíduos expandir os seus horizontes através da leitura e da aprendizagem. A biblioteca também desempenha um papel vital na preservação do património cultural, mantendo arquivos de documentos históricos e tesouros literários.
As variáveis de entrada de cada método individual, incluindo o seu tipo de dados e uma explicação concisa.
As características, o significado ou a natureza do resultado gerado por cada função podem variar em termos do seu valor e classificação.
Para compreender melhor os potenciais problemas associados a um determinado método, é importante considerar tanto os tipos de erros que podem ser lançados pelo método como quaisquer condições ou circunstâncias específicas em que esses erros são mais prováveis de ocorrer. Ao estarem conscientes destes factores, os programadores podem tomar medidas para mitigar os riscos e garantir que o seu código funciona sem problemas numa variedade de situações.
Os comentários no código fornecido contêm duas etiquetas importantes, nomeadamente a etiqueta “@module” e a etiqueta “@example”.A primeira indica que o ficheiro é um módulo, enquanto a segunda fornece um exemplo de código ilustrativo para cada método respetivo. Estas etiquetas servem como referências úteis para os programadores que procuram orientação sobre como utilizar estes métodos de forma eficaz nos seus próprios projectos.
Documentando o código do desenvolvedor da maneira certa
De fato, o JSDoc serve como um meio eficiente para gerar documentação abrangente do código JavaScript por meio da incorporação perfeita no processo de desenvolvimento. Isto facilita a rápida geração de documentação concisa e complexa, permitindo simultaneamente actualizações e revisões contínuas no ambiente do projeto.
Embora a automação fornecida pelo JSDoc possa ser bastante útil na geração de documentação, é essencial que se siga certas directrizes e melhores práticas para garantir a criação de documentação de alta qualidade.