Eae gente bonita, beleza? Recentemente o criador do Svelte Rich Harris anunciou que vai trocar todo o código escrito em TypeScript da sua biblioteca pelo não tão conhecido JSDoc. Pelo TypeScript ser um superset muito conhecido e utilizado essa noticia me gerou um pouco de curiosidade para saber o que exatamente esse JSDoc faz e o que levou a essa troca e eu vou contar um pouco aqui.
O que é JSDocs
Vamos começar pelo começo, o que é o JSDoc? O JSDoc é uma API open source para gerar documentação para o código JavaScript através de comentários. Com o código todo comentado você pode gerar um site com toda a documentação do seu código tornando a navegação nele muito mais fácil.
Exemplo do site gerado 👇🏾
O JSDoc também trabalha muito bem junto ao VSCode colocando os tipos na caixa de ajuda quando você coloca o mouse em cima da chamada da função.
O uso do // @ts-check ajuda bastante fazendo com os tipos sejam inferidos no momento do desenvolvimento e é aqui que o JSDoc começa a brilhar de verdade e coloca a inferência de tipos sem toda a complexidade que o TypeScript traz consigo.
Como o JSDocs funciona
O funcionamento do JSDoc é bem simples, você adiciona um comentário acima da sua função ou variável e adiciona os tipos e quando rodar o comando da API ele vai gerar o site com a documentação, e no vscode ele irá mostrar os tipos, com o @ts-check no inicio do arquivo ele irá mostrar os erros na linha também.
Abaixo vou deixar um exemplo de um código documentado com JSDoc, é uma lib bem interessante porque você consegue definir entidades com ele e ter tipos mais complexos. Os comentários também funcionam para as variáveis. Na documentação existem muitas outras opções para serem usadas nos comentários.
Exemplo de uso do JSDoc:
// @ts-check
/**
* Tipo da entidade `Task`
*
* @typedef {Object} Task
* @property {number} id Id da task
* @property {string} name Nome da task
* @property {string} description Descrição da task
*/
/**
* @constant
* @type {Task[]}
*/
const tasks = [];
/**
* Essa função cria uma tarefa na lista de tarefas. E retorna o Id da tarefa.
* @param {string} name Nome da task
* @param {string} description Descrição da task
* @returns {number}
*/
function addTask(name, description) {
/**
* @type {Task}
*/
const newTask = {
id: tasks.length,
name,
description
};
tasks.push(newTask);
return newTask.id;
}
/**
* Deleta uma task da lista de tarefas.
* @param {number} index Id da task
* @returns {void}
*/
function deleteTask(index) {
tasks.splice(index, 1);
}
/**
* Lista todas as tarefas.
* @returns {void}
*/
function listAllTasks() {
console.log("Lista de tarefas")
console.table(tasks);
}
/**
*
* @param {number} index Id da task
* @returns {Task}
*/
function getTaskById(index) {
return tasks[index]
}
/**
* Executa o projeto
* @returns {void}
*/
function main() {
addTask("Create a article", "Search about the theme");
addTask("Sleep", "Sleep early");
listAllTasks();
const task = getTaskById(1);
console.log(task);
deleteTask(0)
listAllTasks();
}
main();
Vale a troca pelo TypeScript?
Bom eu pesquisei sobre o JSDoc por conta dessa noticia de mudança de algumas libs para usar ele ao invés do TypeScript. Na minha humilde opinião não acho vantajoso porque mesmo você usando o @ts-check e tendo o vscode te ajudando você não tem o momento da compilação do TypeScript onde os tipos são checados novamente e os erros jogados na sua cara. Então o tempo que você economiza sem lidar com os tipos do TypeScript você provavelmente vai gastar debugando o projeto. Não é de todo ruim bem longe disso, mas eu faria essa escolha apenas em projetos menores.
Se chegou até aqui, me segue la nas redes vizinhas.
Referências
JSDocs a Quickstart by @martink
JSDoc Sistema de tipos
TypeScript is not worth...
Turbo 8 is dropping TypeScript
Top comments (0)