Effective JSDocs

JSDoc is a documentation framework for the Javascript language. It takes the form of a comment block with one extra “*” in each line.

It is widely used to document code, but it is often not to its full potential. This article aims to explain how to use the method and showcase some functions that are not that used.

Why NOT use it? It may not be as powerful as Typescript, but it doesn’t require any configuration. As you’ll see with the examples below, it can be very useful while writing code and the next person who has to edit that piece will surely thank you.

Here we have a function named “fn” that receives a parameter “foo”. Above, the documentation defines foo as a parameter with the keyword “@param” and provides a description to it. This description will then be shown in the information about the function.

But notice that the type of the parameter is still shown as “any”. This can be changed by providing a type for the variable inside of the brackets before the parameter name.

Now we can see “foo” marked as a number, as well as the return type of the function, which was inferred.

You can also explicitly define the return type of a function by using the “@return” keyword.

Besides simpler types like number and string, you can write more complex ones, like an object.

For object types, the editor may even be able to provide better code completion.

JSDocs doesn’t actually check your types, so you can write anything. Your IDE, though, may be able to understand some of them and help you based on this information.
For example, you can write things like Promise<number> as the return type of your function and your editor will suggest then, catch and finally when autocompleting for an attribute of the result of this function.

Another useful feature is the ability to define custom types with the “@typedef” keyword. For example, if you have a type “User” that will be used in multiple places, you can define it and use it wherever you need it. Then, if you need to edit something, the changes will be applied everywhere, instead of you needing to edit each location separately.

Continuing on the reusability path, you can also import types from other files. Keep in mind you have to be exporting something in the source file for this to work (don’t ask me why).

Here is an example of how this would all be used in the code for an endpoint to get some user data.

JSDocs can provide a lot of the benefits of supersets like Typescript without all the hassle of configuring the environment. It could be a great option for projects where the benefits of configuring such a tool do not outweigh the effort.

Related posts:

The brand offers Body Hygiene & Hair Care products for men and women, 100% Made in Côte d’Ivoire. Manufactured and distributed by the CFAO group, Ébène is marketed in many West African countries such…

lost it a while back, perhaps ai could answer my question. create the prompt. let the ai do the thing and here’s the result i personally laugh…. but the ai is right, at the end the meaning of life…

When I spied this wonderful challenge by Sharing Randomly and Trista Signe Ainsworth on the amazing Thank You Notes publication, my first thought was producing, carrying, delivering, and raising…