DEV Community

Cover image for JSDoc in TS and JS
Yeom suyun
Yeom suyun

Posted on

JSDoc in TS and JS

Two days ago, I wrote a post about JSDoc.
The post was about using JSDoc for type checking, and it received over 60 comments, including my own replies.


Some of the comments were critical of JSDoc's type checking capabilities, while others defended JSDoc's ability to provide complete type checking.
I was curious about the repetition of the same question and answer, and I realized that we were talking about different JSDoc.

TS JSDoc

In TypeScript, JSDoc is a pure comment.
Although it provides some information when we hover over the code, it does not support type checking at all.
But it's different in JavaScript.

JS JSDoc

By adding a few settings to tsconfig.json, TypeScript can read JSDoc in JavaScript and support the same level of type checking as TypeScript.
This is in stark contrast to the incompetent JSDoc of TypeScript.
Also, even in cases where JSDoc is written but not used with TypeScript, such as in an eslint project, JSDoc is simply a comment.
I agree to some extent that JSDoc can be aesthetically horrible, and it is hard to argue against that.
However, I hope that the misunderstanding that JSDoc does not support adequate type checking will be cleared up, and I will leave an example below of how TypeScript and JSDoc can be used to perform the same type checking.

Thank you.

TypeScript DeepReadonly

JSDoc DeepReadonly

JSDoc function overloads

JSDoc discriminated unions

Top comments (11)

Collapse
 
fibo_52 profile image
Gianluca Casati

eheh I wrote about this 4 years ago fibo.github.io/2019/09/always-use-...

Collapse
 
artxe2 profile image
Yeom suyun

I especially like the title.
The biggest benefit of JSDoc that is currently being discussed is source maps, but it is a good article.

Collapse
 
rampa2510 profile image
RAM PANDEY • Edited

Your post is excellent! The only consideration that holds me back from fully embracing JSDoc is its potential impact on code quality. However, for solo development projects, JSDoc still stands out as the preferred choice

Collapse
 
rampa2510 profile image
RAM PANDEY

Additionally, it would be extremely helpful if you could provide the tsconfig.json code instead of an image. This would enable people to easily try it out and experience its capabilities firsthand.

Collapse
 
artxe2 profile image
Yeom suyun

In the first article of my series, there are links to relevant GitHub and Stackblitz repositories.

Collapse
 
synecdokey profile image
Emilia

It doesn't really support function overloads or discriminated unions. So while JSDocs can be adequate, they do not "perform the same type checking".

Collapse
 
artxe2 profile image
Yeom suyun

That is not true.
I have added examples of how to use those features in JSDoc at the bottom of the text.

Collapse
 
synecdokey profile image
Emilia

Oh, I stand super corrected. This is amazing, thank you!

Collapse
 
brense profile image
Rense Bakker

You can, they just combine d.ts files with jsdoc, making their typings half typescript, half jsdoc because they want to avoid using the typescript compiler for... reasons... 😅

Collapse
 
brense profile image
Rense Bakker

I mean... it's exactly the same jsdoc :B just a different syntax of how you write your types... or even more accurate, the actual type syntax is the same, just the fluff syntax around it is different (absent in typescript).

Collapse
 
artxe2 profile image
Yeom suyun

It is almost true, but there may be some differences in the developer experience when configuring a monorepo, and there are also differences in the provision of source maps when distributing a library.