Typescript has been voted 4th place as the most loved or dreaded language in the StackOverflow survey 2022, which is props actually to Microsoft, if there is one thing they have mastered is creating elegant and fun programming languages.
Besides being elegant, Typescript + the vscode IntelliSense equals Absolute đ„đ„đ„.
one of the few reasons TS is so loved.
but what does all this have to do with JavaScript, @ params, and being 200x faster?
The absolute fire of TS && vscode IntelliSense, is absolutely the same fire we get w/ @ param + Javascript and vscode, done right you may fall in love with JavaScript even deeper.
example of the IntelliSense in action:
@ Param
I think it's time I admit @ param is kinda clickbaity, it's part of a larger concept of JSdocs, @ params is well-known and recognizable I had to use it.
JSDoc
defined as a quick start to documenting JavaScript.
besides documenting your code, JSDoc provides a way for vscode to understand your JavaScript, that's where the magic happens, the beautiful IntelliSense.
@ type example
JSDoc has these @ annotations that describe your code, @param being one of them, @type defines the type of a variable. for example, annotating a string.
w/o JSDoc
with JSDoc
Becoming 200x faster
JSDoc and HTML elements
you can document any element and get free code completion.
gif example: code completion
JSDoc and Primitive types
/**
- @type {String}
*/
let str;
/**
- @type {Array}
*/
let arr;
/**
- @type {Object}
*/
let obj;
/**
- @type {Number}
*/
let num;
/**
- @type {Boolean}
*/
let bool;
JSDoc and complex Arrays or Objects
more of the documenting side than code completion.
/**
- @type {Array<String>}
*/
let arr = []
/**
- @type {{a: String, b: Number}}
-
*/
let obj;
JSDoc and functions
You can go deeper or wide as you want, and get free code completion. JSDoc was designed for documentation, allowing developers to communicate the functionality of their JS code and their types, vscode just leveraged it for IntelliSense.
IDE's
Thanks to @jfbrennan for pointing this out in the comments, which I totally missed, JSDoc is supported by almost all IDE's with some having it's own extended variation.
app script example - extended variation
Outro
JSDoc is a neat trick to know, to learn more you can visit their site for in-depth documentation and more cool features.
with that, have a good day or nightđ€đŒ. Thanks for reading!
Top comments (4)
Speaking from vscode experience here (I'm not sure how other editors handle it, but surely they have plugins to emulate what I'm going to say if it's not native)
It can be a nice substitute if you don't have enough complexity to justify the overhead of TS, or if you don't know TS, since you can get a pretty rich non-blocking experience. If you tell it to, VS will automagikally process JSdoc annotated types in all of your files within its TS server (yes vscode runs an internal TS server in the background). Important caveat: it won't automatically throw errors for files that aren't open & it won't warn you (or stop you) when it comes time to compile.
It's still very powerful. It supports a lot of TS-like behavior, such as importing types from .ts or .d.ts files through comments:
as well as define your own custom types in .js files
You can also use more advanced TS features like generics ("
@template") although the more clever you get, the more verbose it gets.Very nice being able to document promisify'd responses:
Definitely worth looking into, especially if you're someone who has been curious about TS but never gave it a try because you didn't want to learn it all.
I had no idea this was possible, so cool Definitely gonna look it up!!!, I knew about the internal TS server, and only used it with types like this:
not define my own, will definitely try it, if you don't mind I could add a section on this too in the article, of course with attribution.
I'm lazy and don't want to read. Is JSDoc TypeScript-powered? Like whenever I do a
@type, is it defined according to the TypéScript rules for types?Thank you Jordan, and yes I totally agree, as much as I like TS, sometimes you just want to get up and running, w/o the overhead, tooling etc.
thank you for pointing that out, I've updated the article to include the IDE's support section to point that out thanks.