DEV Community

Boost Your JavaScript with JSDoc Typing

Samuel Braun on April 08, 2023

There are many reasons why you can't or don't want to use TypeScript in your project. One common reason is that you are using a legacy codebase tha...

Read full post

Imam Ali Mustofa • Apr 9 '23

This is what am looking for. Thanks @samuel-braun 🔥🔥

Maarten Berkenbosch • Sep 12 '23

I can't find any documentation about linking namespaces modules memberof etc etc.
I'm looking for examples with a hierarchy.
eg.

backend/logic/api.js (with methods and variables)
backend/logic/cache.js

How do I set this up?
namespace: backend ?
module: logic?
api: memberof logic?

functions in api.js memberof api ?

I have no clue how to organise this and on top of that @link syntax is so confusing (and doesn't work most of the time)

Samuel Braun • Sep 13 '23 • Edited

Im not too sure what you are looking for, but here is how you could use namespaces and modules to structure your code:

api.js

/**
 * @namespace backend
 */

/**
 * @module api
 * @memberof backend
 */

/**
 * A function in the api.js file.
 * @function someFunction
 * @memberof module:api
 */
function someFunction() {
  // your code here
}

/**
 * A variable in the api.js file.
 * @var {number} someVariable
 * @memberof module:api
 */
const someVariable = 123;

cache.js

/**
 * @module cache
 * @memberof backend
 */

/**
 * A function in the cache.js file.
 * @function anotherFunction
 * @memberof module:cache
 */
function anotherFunction() {
  // your code here
}

anywhereElse.js

/**
 * This function does something with {@link module:api.someFunction}.
 */
function yetAnotherFunction() {
  // your code here
}

Sergey Leschev • Apr 15 '23

I would like to stress the importance of writing clean and maintainable code. It's essential to keep in mind that the code we write is not just for us but for others who might work on the project in the future. Therefore, it's crucial to follow coding standards and best practices, choose descriptive and meaningful variable names, and write comments wherever necessary to make code more readable and understandable.

Another crucial aspect of writing quality code is testing. Testing should be an integral part of the development process, and all code changes should undergo automated tests to ensure that they are working as expected. This helps catch bugs early on and saves time and effort in identifying and fixing them later in the development cycle.

Samuel Braun • Apr 15 '23

Absoloutely Sergey 👍, It's like you read my mind. Im currently writing a post about that exact topic (variable naming and code readability). Im just waiting to get approval to use a piece of code as an example and I can publish it. So it'll be around start of next week.

Mark Roeling • May 14 '23

wondering: does it help in "parsing" runtime, in a browser? What is the effect perfomance-wise?

Samuel Braun • Sep 13 '23 • Edited

Not sure exactly what you mean with parsing at runtime. JSDoc wasn't meant to be run in the browser. But if you want to validate types for exmaple of an API you could use something like Zod. With Zod you can also type your code using the same schema a JSDoc:

const myUserSchema = z.object({
    user: z.string(),
    age: z.number(),
});
// @type {z.infer<typeof myUserSchema>}
const user = await fetch("user.json");

// Validate if data is actually same type as defined in the schema
// Throws an error if not
myUserSchema.parse(user);

José María CL • Mar 16

Great article!

Kevin Bridges • Apr 12 '23 • Edited

Great article Samuel ... thanks for sharing.

FYI: There is a minor fo paux in the "Other JSDoc tags" section, where a previous code sample has broken the article content into a coding pre tag.

Samuel Braun • Apr 12 '23

Thank you for telling, I've fixed it ✔

Fabien Arcellier • Apr 12 '23 • Edited

This is exactly the wrap up I was looking for. I enjoy the attention to details you have done @samuel-braun.

I would appreciate to have a way to navigate quickly in the article. Have you considered to add a table of content in the article ? (@derlin has developped a toc generator for dev.to if you need)

Samuel Braun • Apr 12 '23

Thank you for this suggestion, thats a great idea. Aaand Done!

t7yang • Apr 12 '23

I did write a very similar article two years ago.
But not many people know.
dev.to/t7yang/type-safety-in-javas...

fruntend • Apr 10 '23

Сongratulations 🥳! Your article hit the top posts for the week - dev.to/fruntend/top-10-posts-for-f...
Keep it up 👍

Samuel Braun • Apr 10 '23

Wow, I didnt expect my first post to explode like that. Thank you all for the kind words and feedback. I will definitely continue writing more posts in the future. ❤

Andrea Giammarchi • Apr 12 '23

I love TS in JSDoc and this post seems to have nailed down most common questions with examples and reasoning. Thank you!

Manrike Villalobos Báez • Apr 12 '23

WONDERFUL article! Thank you so much!!!

vhs • May 6

It's also possible to create a types.d.js file for app-wide type definitions.

Samuel Braun • May 9

Absolutely, it's described in more detail here: #dts-files

Renato Brito • Apr 12 '23

Wow! This article is amazing and easy to understand. Thanks, @samuel-braun .

Michael Leahy • Jul 9 '23

Great article @samuel-braun; I refer a lot of folks to it. I just want to drop a potential valuable resource for folks that are going down the JSDoc + TS route and this is a NPM package I've been developing for the past 1.5 years for automatic TS declaration generation from ESM / JSDoc: @typhonjs-build-test/esm-d-ts. It has all sorts of nice features for library developers including support for sub-path exports and more. If you think it is a good resource to add to the "Additional Resources" section of the article that's awesome.

In the coming months I'm also working on a package w/ a CLI to automatically generate documentation from the generated TS declarations from ESM + JSDoc.

Cherlock Code 🔎 • Apr 8 '23

Thank you for this great and thorough explanation of using JS docs. I've recently been exploring using them myself so this was very insightful :)

Samuel Braun • Apr 8 '23 • Edited

Thanks alot, I'm happy you liked it. At my company we're currently adapting JSDoc and its a big change for everyone writing JavaScript. I often end up helping them with doing their types. So I hope this gets rid of their confusion and other developers aswell.

howsmyanimeprofilepicture • Sep 10

Well summarized post. I am using this post as my JSDoc cheatsheet. Thank you!

Xoomies • Apr 9 '23

This is very in-depth! Great explanation! I will definitely be referencing this for any JSDoc projects I might have! Thank you!