O que é JSDoc
Tags: javascript, node, nodebr, braziliandevs
Published: 2023-11-11 20:50:42

Eae gente bonita, beleza? Recentemente o criador do [Svelte](https://svelte.dev/) Rich Harris anunciou que vai trocar todo o código escrito em TypeScript da sua biblioteca pelo não tão conhecido [JSDoc](https://github.com/jsdoc/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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ut7586xmrtqkgt2nbkek.png)



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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rw7witluwidnpqhupkkb.png)



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:
```JavaScript
// @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.](https://bento.me/cmsdev)
![obrigado](https://media.giphy.com/media/D08aklo5n0hi5PJyZw/giphy.gif)

## Referências

[JSDocs a Quickstart by @martink](https://medium.com/@martink_rsa/js-docs-a-quickstart-guide-da6ce5df4a73)
[JSDoc Sistema de tipos](https://lucasviana.dev/blog/jsdoc-sistema-de-tipos/)
[TypeScript is not worth...](https://devclass.com/2023/05/11/typescript-is-not-worth-it-for-developing-libraries-says-svelte-author-as-team-switches-to-javascript-and-jsdoc/)
[Turbo 8 is dropping TypeScript](https://world.hey.com/dhh/turbo-8-is-dropping-typescript-70165c01)