Sometimes, JSDoc is just enough

For the uninitiated, jsdoc is just the defacto way of documenting javascript/typescript. You’ve probably been using it knowingly or unknowingly forever.

/** 
 * Go get some data 
 * @param param The search parameter
 * @returns a promise that resolves to the data
 */
async function getSomeData(param) {
    return await (await fetch(`https://httpbin.org/get?boop=${param}`)).json();
}

If you know, you know. The above is missing something really important, the types!

/** 
 * Go get some data 
 * @param {string} after The search parameter
 * @returns {Promise<{data: string}>} a promise that resolves to the data
 */
async function getSomeData(param) {
    return await (await fetch(`https://httpbin.org/get?boop=${param}`)).json();
}

Why?

Great, you’ve got some types in your project. What you are very validly wondering is, well, what use is that when we have typescript?

There isn’t an official article, but you’ll hear rumors of the svelte project “dropping typescript”. This was misinterpreted heavily. They didn’t drop types, they dropped typescript. They’re using jsdoc for typing. In fact, even using the javascript template in sveltekit still brings in typescript as a dependency. tsc is really just a type checker, plus a little compiler that mostly strips out types. It’s designed that way!

If you just want to use the type-checker, you can use jsdoc. As you get more complex types, you can just start to use ts files. But then the question of, “okay, well if you still have to configure typescript, why not just use it?” comes up, and is also valid. Well, the general argument is that you don’t really need “.d.ts” files to start getting editor completion in things like intellij or vscode. You can just use jsdoc. The other big thing is that you get to skip the compile step. If you’re writing a library, you can upload your original .js files to npm and skip all of that.

Conclusion

I like it! I use jsdoc in a legacy project that I’m working on and it brings an immediate improvement to the developer experience. I don’t have to go through the political and technical challenges of introducing typescript but I still get types.