I have re­cently taken an in­ter­est in TypeScript. Not just be­cause it brings fea­tures that are con­sid­ered es­sen­tial to pro­duc­tion-grade ap­pli­ca­tions, but also be­cause it makes us­ing a code ed­i­tor such as Atom or VS Code more use­ful for me.

However, I was not very keen on the idea of con­fig­ur­ing the TypeScript com­piler on every pro­ject I wanted just for type an­no­ta­tions and au­to­com­plete sug­ges­tions. Code ed­i­tors al­ready have come a long way when it comes to sug­ges­tions, but I also wanted to in­cre­men­tally adopt my own type de­f­i­n­i­tions, thus re­mov­ing my re­liance on some very smart guesses by a code ed­i­tor.

So, fun­nily enough, while go­ing through some code be­hind IndieKit, a Micropub server I am us­ing while build­ing Celestial, I was in­trigued by a very dis­tinc­tive com­ment block just be­fore some func­tion de­f­i­n­i­tions.

Here’s what it looks like:

* @param {boolean} update - updates the logged in state
* @returns {boolean} - returns a success/error indicator

This was­n’t the first time I saw it in open source pro­jects. However, it def­i­nitely was the first time I wanted to ex­plore this. There is a sense of longe­tiv­ity in want­ing to self doc­u­ment code with­out the ad­di­tional bur­den and build step of a com­piler. Or leav­ing com­ments every­where with no sense of or­ga­ni­za­tion to it.

This com­ment block comes from JSDoc. An in­tended use-case is gen­er­at­ing an HTML doc­u­ment based on all your JSDoc de­f­i­n­i­tions. Make freshly hired de­vel­op­ers happy! 😊

VS Code of­fers built-in in­te­gra­tion. Typing /** will lead it to sug­gest a JSDoc block. Hit en­ter and you’re on your way. Type @ and you get a bunch of tag sug­ges­tions. It un­der­stands most of JSDoc, though I have come across in­stances where it fell short from the doc­u­men­ta­tion.

Okay, so your pro­ject has grown a bit. Quite a bit. It’s time to use TypeScript but your code is now un­hap­pily lit­tered with JSDoc. Worry not; VS Code of­fers you an op­tion to in­fer type an­no­ta­tions from JSDoc and fill them in for you. So cool, right?

I’ll leave you to ex­plore it, pos­si­bly learn and start us­ing it. It does cir­cum­vent the TypeScript tax for sim­ple pro­jects — per­haps even mid-size pro­jects.