Return String

Introduction To JSDoc

Updated 2020-07-27

Learn to document your code with JSDoc for JavaScript providing helpful tooltips while you develop. This is a beginner friendly tutorial that only assumes you know basic JavaScript.

JSDocs allows us to add some easy documentation along with type information to our declarations. Using JSDoc can help readers of our code understand it at a glance, but it also helps code editors display tooltips.

Documentation blocks are created by using a multi line comment /* Multi-line comment */ but with an extra asterisk in the beginning like so: /** JSDoc */. Inside the block we can add a description, including some special keywords to give us type information.

Descriptions

With JSDocs we can describe a function for our users with a short and a long description. The short description will generally be the first line in the JSDoc block. An optional longer description can be added by creating a line with only an asterisk (*) between the short and long descriptions.

/**
 * This is the short description
 *
 * This is the longer description that goes into more detail
 */
function add(x, y) {
    return x + y;
}

This gives a great overview of what a function does to a reader of our code. However, the real magic comes from code editors being able to use this information to display tooltips as you code.

Tooltip for add function with description

Adding Types to Functions

To help describe the inputs and output of functions, we can add keywords to our JSDoc block starting with @ such as @param to describe a function parameter.

Using the @param keyword will let us set a type and describe each parameter of a function: @param {type} nameOfParameter Description. Designating a type tells the user of the function what the function expects as parameters. We can do the same for the return value by using @returns with a type and description.

Expanding our JSDoc for the add function, we can write documentation for the parameters and return value like so:

/**
 * This is the short description
 *
 * This is the longer description that goes into more detail
 *
 * @param {number} x A number to be added
 * @param {number} y A number to be added
 * @returns {number} The combined numbers
 */
function add(x, y) {
    return x + y;
}

We now have rich type information, both when reading the code and through tooltips when using the function in our code.

Tooltip for add function with description and types

With type information it is easier than ever to use your function without worrying about what it does internally.

Next Steps

JSDoc

JSDoc has a lot more tags we can use than @param and @return and can even generate documentation files for you: Learn more about JSDoc on their official website. You can document anything from copyright notices to single variables.

TypeScript

If you found value in adding types to your code, you may want to learn more about TypeScript. TypeScript will allow you to add simple and complex types directly in your code. It uses a compiler to verify that you do not pass the wrong type to your function when calling it, and it outputs normal JavaScript.

If we wrote our add function again in TypeScript it would look like this:

function add(x: number, y: number): number {
    return x + y;
}

It is worth noting that TypeScript is a superset of JavaScript. This means that you can write JavaScript in a TypeScript file, and all of TypeScripts features are optional: Making it fairly easy getting started as you can choose which TypeScript features and rules you want to use.