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