Bruno NorillerFirst: no, didn’t create a new framework, so no worries. (JSDocScript isn’t really a thing, I think). Second: just use Typescript! But when you can’t… then read on!
There are a bunch of benefits to using Typescript, everyone knows that.
The problem is that this isn’t true for the people of the past (poor them), so you will probably still find a lot of legacy projects in Vanilla JS.
So, before you start crying, again, because the IDE doesn’t help you with anything and rage over hours wasted because of a typo that the framework just said “hey there’s an error” and then you in vain kept asking the screen with “yes, I know there’s an error, but WHERE?” and then the framework just like “¯_(ツ)_/¯”. (If this is based on real events? I won’t confirm nor deny.)
Anyway… the more you use Typescript, the more you feel like missing a limb when you have to use Vanilla JS, but the thing people don’t tell you is: JSDOC!
An example
I put together a little Todo example for you to play with:
(don’t mind the example much… have I ever said that I’m awful at creating examples?)
Anyway, for this you need to open an IDE to check all the types, I also left a lot of comments.
Yes, this is React, but you can use JSDOC with anything!
They are just comments that your IDE interprets, so there’s no need to “compile” them.
Need more?
I’m of the opinion that your documentation (and JSDoc, even TS, is a type of documentation) needs to be the closest it can be to where you use it.
But for some cases where you can create a d.ts file that will help you and your colleagues with advanced stuff. And that will totally ignored by compilers and anything else!
I usually create it to copy utilities that JSDoc might not support out of the box or any utility I might need (doing extend this or infer with multiple generics is really hard in JSDoc (although not impossible for many things, mind you)).
Caveats
Unfortunately, JSDoc is not TS. Not only that, it’s really limited in what it can do.
Don’t get me wrong. It’s amazing in what it can do, but there are things it just can’t.
Not only that, it’s verbose! You need a lot to do the same as with TS.
And an important one: from what I understood, the way the JSDoc comments are interpreted into usable types might be different depending on the IDE… if you’re using VSCode you can do anything you’ll find out there about it, but for others, I’m not sure.
How to start
If you check the example again, you will see a // @ts-check at the top of the file.
You will need this in every file you want to be checked or you can add checkJs: true to a jsconfig.json (in this case, you can add a // @ts-nocheck to the files you don’t want checking.
You also want, in your VSCode settings, to search and check true checkJs or add "js/ts.implicitProjectConfig.checkJs": true to the settings JSON.
When to start
If you’re in a legacy project and like TS, but you have JS and can’t migrate to TS, for any reason, then start NOW!
You can start with the feature/fix you’re working on, then expand to utilities… also, bring your colleagues on it with you!
And when you just show the “magic” of types working to your fellow programmers, then I don’t think you need arguments.
The less you wait, the fewer problems you’ll have (and you’ll probably have enough of them). So, the first thing you have to do is set stuff up and start sprinkling the types (VSCode is really smart, so you don’t really need to type everything and the more you do, the more you’ll be helped by it).
My experience with the adoption
In my case, I ended up using a whole day or two just making and passing types that the frontend was using, but because I never had to think about actually typing them, then I had a lot of problems even figuring out what I had in there (I was just coming back from vacations).
I still had a lot of problems thereafter (it was a HUGE feature), but it’s totally worth it! Every time it just knows what I’m using and gives me completions and errors on typos… it’s bliss.
Sources you can use
The official docs (which are really bad TBH)
The typescript one (that doesn’t really help much, but hey! all of this is powered by TS)
https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html
And then there are a lot of people who already wrote about this, this one is a little outdated, but still gives a lot of good info and saved me more than a few times
