DEV Community

Cover image for O que é JSDoc
Cristian Magalhães
Cristian Magalhães

Posted on • Updated on

O que é JSDoc

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 👇🏾

Image description

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.

Image description

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();

Enter fullscreen mode Exit fullscreen mode




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.
obrigado

Referências

JSDocs a Quickstart by @martink
JSDoc Sistema de tipos
TypeScript is not worth...
Turbo 8 is dropping TypeScript

Top comments (0)