JS Docs

Introduction

Imagine you've written a function three months ago. You come back to use it and can't remember what parameters it needs or what it returns. You have to dig through the code to figure it out. Now imagine your teammate needs to use your function—they have the same problem, but they also can't ask you because you're on holiday.

JSDocs solves this problem. It's a standardized way to document your code that:

1. Gives developers information about your code when they hover over it in VS Code
2. Enables TypeScript-style type checking without writing TypeScript
3. Can automatically generate documentation websites for your projects

By the end of this lesson, you'll be able to document any function professionally.

How to Use JSDocs

JSDocs works by adding information between special opening and closing comment tags: /** */. This comment block goes directly above a function.

NOTE: Any lines between the /** and */ tags need to have a * at the front. VS Code will automatically insert this for you when you press Enter while your cursor is inside a JSDoc comment.

Let's start with simple examples—a regular JavaScript function.

TIP: JSDocs is smart and will detect your function's parameters and return value. It's best to add JSDocs after you've finished writing the function so you can take advantage of this autocompletion.

Normal JS Function

1
/**
2
 * Adds two numbers together
3
 */
4
export function addNumbers(a, b) {
5
  return a + b;
6
}

When you hover over either of these in VS Code, you'll see a tooltip containing the description from the JSDoc comment:

[Image: Screenshot showing VS Code tooltip displaying JSDoc description "Adds two numbers together" when hovering over the addNumbers function]

This is incredibly useful for other developers (including future you) who want to use your functions and components without reading through all the code.

Common Data Types for JSDocs

Before we go further, here are the data types you'll use most often:

Union Types

You can specify that a parameter accepts multiple types using the pipe | symbol:

1
/**
2
 * Displays a message to the user
3
 * @param {string|number} id The user ID (can be string or number)
4
 */
5
function getUser(id) {
6
  // ...
7
}

Nullable Types

Use ? before the type to indicate a value can be null:

1
/**
2
 * Finds a user by email
3
 * @param {string} email The email to search for
4
 * @returns {?Object} The user object, or null if not found
5
 */
6
function findUserByEmail(email) {
7
  // ...
8
}

@param

The @param tag documents your function's parameters, including their types and descriptions. This is essential for helping other developers understand what values to pass in.

NOTE: TypeScript can automatically convert JSDocs types to TypeScript types. If you see a white squiggle under a function name with the message JSDoc types may be moved to TypeScript types, you can use Quick Fix to select Annotate with type from JSDoc for automatic conversion.

Syntax

1
/**
2
 * Example function
3
 * @param {dataType} parameterName Parameter description
4
 */

• dataType: The data type of the parameter (e.g., string, number)
• parameterName: The exact name of the parameter as it appears in your function
• Parameter description: A brief explanation of what this parameter is for

Practical Example

Let's add @param tags to our addNumbers function:

1
/**
2
 * Adds two numbers together
3
 * @param {number} a First value to add
4
 * @param {number} b Second value to add
5
 */
6
export function addNumbers(a, b) {
7
  return a + b;
8
}

@returns

The @returns tag documents what your function returns, including the data type and a description.

Syntax

1
/**
2
 * Example function
3
 * @returns {dataType} Description of the return value
4
 */

Practical Example

Let's extend our addNumbers function to include @returns:

1
/**
2
 * Adds two numbers together
3
 * @param {number} a First value to add
4
 * @param {number} b Second value to add
5
 * @returns {number} The sum of both parameters
6
 */
7
export function addNumbers(a, b) {
8
  return a + b;
9
}

@example

The @example tag is one of the most valuable additions to your documentation. It shows other developers exactly how to use your function with real code. When done well, it looks professional and saves time.

The @example tag uses Markdown syntax, which means you can add syntax-highlighted code blocks.

Adding Syntax Highlighting with Markdown

You can wrap your code in triple backticks with a language identifier:

```js
console.log('Hello world');
```

You can use js for JavaScript, jsx for React, ts for TypeScript, and tsx for React TypeScript.

Practical Example

Let's add an @example to our addNumbers function:

1
/**
2
 * Adds two numbers together
3
 * @param {number} a First value to add
4
 * @param {number} b Second value to add
5
 * @returns {number} The sum of both parameters
6
 * @example
7
 * ```js
8
 * const a = 1;
9
 * const b = 2;
10
 * const sum = addNumbers(a, b);
11
 * console.log(sum); // 3
12
 * ```
13
 */
14
export function addNumbers(a, b) {
15
  return a + b;
16
}

Your tooltip will now show everything—types, descriptions, and a working example:

[Image: Screenshot showing VS Code tooltip with full JSDoc documentation including function signature with types, description, @param details, @returns, and @example code block with syntax highlighting]

Optional Parameters

You can mark a parameter as optional by wrapping its name in square brackets [ ].

Syntax

1
/**
2
 * Example function
3
 * @param {dataType} [optionalParameterName] Description of optional parameter
4
 */

This is equivalent to TypeScript's optional property syntax:

1
type MyType = {
2
  optionalParameterName?: dataType;
3
};

Practical Example

1
/**
2
 * Adds two numbers together
3
 * @param {number} a First value to add
4
 * @param {number} [b] Second value to add (optional)
5
 * @returns {number} The sum of both parameters
6
 */
7
export function addNumbers(a, b = 10) {
8
  return a + b;
9
}

Default Values

You can also document the default value using = inside the brackets:

1
/**
2
 * Adds two numbers together
3
 * @param {number} a First value to add
4
 * @param {number} [b=10] Second value to add (defaults to 10)
5
 * @returns {number} The sum of both parameters
6
 */
7
export function addNumbers(a, b = 10) {
8
  return a + b;
9
}

@typedef

@typedef lets you define custom types that you can reuse throughout your code. This is similar to creating a type or interface in TypeScript.

TIP: Define your @typedef blocks at the top of your file or in a separate types file to keep your code organized.

Syntax

1
/**
2
 * Description of the type
3
 * @typedef {baseType} TypeName
4
 */

Practical Example

1
/**
2
 * A value that can be either a number or a string containing a number
3
 * @typedef {number|string} NumberLike
4
 */
5

6
/**
7
 * Adds two number-like values together
8
 * @param {NumberLike} a First value
9
 * @param {NumberLike} b Second value
10
 * @returns {number} The sum of both values
11
 */
12
export function addNumbers(a, b) {
13
  return Number(a) + Number(b);
14
}

Complex Objects

Functions often accept objects with multiple properties. There are three ways to document these in JSDocs.

Option 1: Inline Destructuring

Best for simple objects with few properties:

1
/**
2
 * Creates a greeting message
3
 * @param {{name: string, age: number}} person The person to greet
4
 * @returns {string} A personalized greeting
5
 */
6
function greet(person) {
7
  return `Hello ${person.name}, you are ${person.age} years old!`;
8
}

Option 2: Dot Notation

Best for documenting each property with detailed descriptions:

1
/**
2
 * Creates a greeting message
3
 * @param {Object} person The person to greet
4
 * @param {string} person.name The person's full name
5
 * @param {number} person.age The person's age in years
6
 * @returns {string} A personalized greeting
7
 */
8
function greet(person) {
9
  return `Hello ${person.name}, you are ${person.age} years old!`;
10
}

Option 3: Using @typedef

Best for reusable types used across multiple functions:

1
/**
2
 * Represents a person
3
 * @typedef {Object} Person
4
 * @property {string} name The person's full name
5
 * @property {number} age The person's age in years
6
 */
7

8
/**
9
 * Creates a greeting message
10
 * @param {Person} person The person to greet
11
 * @returns {string} A personalized greeting
12
 */
13
function greet(person) {
14
  return `Hello ${person.name}, you are ${person.age} years old!`;
15
}

JSDocs for React Components

React components benefit greatly from JSDocs because they clearly document props. Let's look at progressively more complex examples.

Basic Component with Props

1
/**
2
 * Displays a greeting message to a user
3
 * @param {Object} props Component props
4
 * @param {string} props.name The user's name to greet
5
 */
6
export default function Greeting({ name }) {
7
  return <div>Hello, {name}!</div>;
8
}

Component with Multiple Props and Events

1
/**
2
 * A reusable button component with loading state
3
 * @param {Object} props Component props
4
 * @param {string} props.label The button text
5
 * @param {boolean} [props.isLoading=false] Whether the button shows a loading state
6
 * @param {boolean} [props.disabled=false] Whether the button is disabled
7
 * @param {'primary'|'secondary'|'danger'} [props.variant='primary'] The button style variant
8
 * @param {Function} props.onClick Click handler function
9
 * @example
10
 * ```jsx
11
 * <Button
12
 *   label="Save Changes"
13
 *   variant="primary"
14
 *   isLoading={isSaving}
15
 *   onClick={handleSave}
16
 * />
17
 * ```
18
 */
19
export default function Button({
20
  label,
21
  isLoading = false,
22
  disabled = false,
23
  variant = "primary",
24
  onClick,
25
}) {
26
  return (
27
    <button
28
      className={`btn btn-${variant}`}
29
      disabled={disabled || isLoading}
30
      onClick={onClick}
31
    >
32
      {isLoading ? "Loading..." : label}
33
    </button>
34
  );
35
}

Using @typedef for Props (Cleaner Approach)

For components with many props, define a type first:

1
/**
2
 * Props for the ProductCard component
3
 * @typedef {Object} ProductCardProps
4
 * @property {string} title The product title
5
 * @property {number} price The price in dollars
6
 * @property {string} imageUrl URL to the product image
7
 * @property {boolean} [inStock=true] Whether the product is in stock
8
 * @property {Function} onAddToCart Callback when add to cart is clicked
9
 */
10

11
/**
12
 * Displays a product card with image, price, and add to cart button
13
 * @param {ProductCardProps} props Component props
14
 * @example
15
 * ```jsx
16
 * <ProductCard
17
 *   title="Wireless Headphones"
18
 *   price={79.99}
19
 *   imageUrl="/images/headphones.jpg"
20
 *   onAddToCart={() => addToCart(productId)}
21
 * />
22
 * ```
23
 */
24
export default function ProductCard({
25
  title,
26
  price,
27
  imageUrl,
28
  inStock = true,
29
  onAddToCart,
30
}) {
31
  return (
32
    <div className="product-card">
33
      <img src={imageUrl} alt={title} />
34
      <h3>{title}</h3>
35
      <p>${price.toFixed(2)}</p>
36
      {inStock ? (
37
        <button onClick={onAddToCart}>Add to Cart</button>
38
      ) : (
39
        <span className="out-of-stock">Out of Stock</span>
40
      )}
41
    </div>
42
  );
43
}

Documenting Children Props

1
/**
2
 * A card wrapper component that provides consistent styling
3
 * @param {Object} props Component props
4
 * @param {React.ReactNode} props.children The content to display inside the card
5
 * @param {string} [props.title] Optional card title
6
 * @param {string} [props.className=''] Additional CSS classes
7
 */
8
export default function Card({ children, title, className = "" }) {
9
  return (
10
    <div className={`card ${className}`}>
11
      {title && <h2 className="card-title">{title}</h2>}
12
      <div className="card-body">{children}</div>
13
    </div>
14
  );
15
}

VS Code Tips for JSDocs

Quick Generation Shortcut

Type /** directly above a function and press Enter. VS Code will automatically generate a JSDoc template with @param and @returns based on your function signature.

[Video/GIF: Demonstrating the /** + Enter shortcut]

Hover to Preview

Hover over any function name to see its JSDoc documentation rendered in a tooltip. This works for your own code and imported libraries.

Go to Definition

Press Ctrl+Click (Windows/Linux) or Cmd+Click (Mac) on a function name to jump to its definition, including the JSDoc comment.

Problems Panel

VS Code will show warnings if your JSDoc types don't match how you're using the function. Check the Problems panel (Ctrl+Shift+M or Cmd+Shift+M) for these hints.

Enable Type Checking in JavaScript

Add this comment at the very top of any .js file to enable TypeScript-style type checking based on your JSDocs:

1
// @ts-check

Now VS Code will show errors if you pass wrong types:

1
// @ts-check
2

3
/**
4
 * Adds two numbers together
5
 * @param {number} a First number
6
 * @param {number} b Second number
7
 * @returns {number} The sum
8
 */
9
function add(a, b) {
10
  return a + b;
11
}
12

13
add("hello", "world"); // Error: Argument of type 'string' is not assignable to parameter of type 'number'

Common Mistakes to Avoid

❌ Mistake 1: Type in the Wrong Position

1
// WRONG - type is after the parameter name
2
/**
3
 * @param name string The user's name
4
 */
5

6
// CORRECT - type is in curly braces before the parameter name
7
/**
8
 * @param {string} name The user's name
9
 */

❌ Mistake 2: Forgetting Curly Braces Around Types

1
// WRONG - missing curly braces
2
/**
3
 * @param string name The user's name
4
 */
5

6
// CORRECT
7
/**
8
 * @param {string} name The user's name
9
 */

❌ Mistake 3: Parameter Names Don't Match

1
// WRONG - JSDoc says "username" but function uses "name"
2
/**
3
 * @param {string} username The user's name
4
 */
5
function greet(name) {
6
  return `Hello, ${name}`;
7
}
8

9
// CORRECT - names match exactly
10
/**
11
 * @param {string} name The user's name
12
 */
13
function greet(name) {
14
  return `Hello, ${name}`;
15
}

❌ Mistake 4: Wrong Brackets for Optional Parameters

1
// WRONG - using parentheses
2
/**
3
 * @param {string} (name) Optional name
4
 */
5

6
// WRONG - using angle brackets
7
/**
8
 * @param {string} <name> Optional name
9
 */
10

11
// CORRECT - using square brackets
12
/**
13
 * @param {string} [name] Optional name
14
 */

❌ Mistake 5: Vague Descriptions

1
// WRONG - unhelpful descriptions
2
/**
3
 * Does stuff
4
 * @param {string} s The string
5
 * @returns {string} The result
6
 */
7
function formatName(s) {
8
  return s.toUpperCase();
9
}
10

11
// CORRECT - clear, specific descriptions
12
/**
13
 * Converts a name to uppercase for display in headers
14
 * @param {string} name The user's full name
15
 * @returns {string} The name in uppercase
16
 */
17
function formatName(name) {
18
  return name.toUpperCase();
19
}

When Should You Add JSDocs?

Not every function needs full documentation. Here's a practical guide:

Always Document

• Exported functions and components — Anything you export will be used elsewhere
• Complex functions — If the function does something non-obvious
• Functions with multiple parameters — Especially if parameter order matters
• Utility functions — Reusable helpers used throughout your project
• API functions — Functions that fetch data or interact with external services

Optional to Document

• Simple one-liner functions — const double = (n) => n * 2 is self-explanatory
• Internal helper functions — Private functions only used in one place
• Event handlers with obvious names — handleSubmit, handleClick may not need docs

Practical Rule of Thumb

Ask yourself: "If I came back to this code in 3 months, would I understand it immediately?"

If the answer is no, add JSDocs.

Generating Documentation

One of the powerful benefits of JSDocs is automatic documentation generation. JSDocs can create a complete HTML documentation website for your project.

Step 1: Install JSDocs

Add the jsdoc library to your dev dependencies:

1
npm i jsdoc --save-dev

Step 2: Run JSDocs on a Single File

You can generate documentation for a single file. For example, if your file is called utils.js:

1
node_modules/jsdoc/jsdoc.js utils.js

Step 3: View the Generated Documentation

If successful, you'll see an out folder created in your project. This folder contains your complete documentation website. Open out/index.html with the Live Server extension to view it.

[Image: Screenshot of generated JSDoc HTML documentation page showing the addNumbers function with its full documentation including description, parameters table, returns information, and example code block in a clean, styled layout]

[Video: Generating JS Docs documentation]

Generating Documentation for a Whole Project

Running JSDocs on individual files isn't practical for real projects. Let's set up a configuration file to document your entire project.

Create a Configuration File

1. Create a conf.json file in the root of your project.
2. Add the following code:

{
  "source": {
    "include": ["."],
    "exclude": ["node_modules/"]
  }
}

This configuration:

• Includes all files and folders from the root directory
• Excludes the node_modules folder (you don't want to document third-party code)

Run JSDocs with the Configuration

Use the -c flag for the configuration file and -r flag for recursive scanning:

1
node_modules/jsdoc/jsdoc.js -c ./conf.json -r

Add a Script to package.json

Instead of remembering this command, add it as a script in your package.json:

{
  "scripts": {
    "docs": "jsdoc -c ./conf.json -r"
  }
}

Now you can generate documentation with a simple command:

1
npm run docs

JSDocs Video

We take a look at the basics of JSDocs and how to add them to a function.

[Video: Video tutorial covering the basics of JSDocs and how to add them to a function]

Exercises

Practice adding JSDocs to functions. For each exercise, add the appropriate JSDoc comments above the provided function.

Exercise 1: Basic Documentation

Add a JSDoc comment with a description to the following function:

1
function greetUser(name) {
2
  return `Hello, ${name}!`;
3
}

Exercise 2: Adding Parameters

Add JSDoc documentation to the following function, including @param tags with types and descriptions for each parameter:

1
function calculateArea(width, height) {
2
  return width * height;
3
}

Exercise 3: Parameters and Returns

Add complete JSDoc documentation to the following function, including a description, @param tags, and a @returns tag:

1
function convertToUpperCase(text) {
2
  return text.toUpperCase();
3
}

Exercise 4: Adding an Example

Add JSDoc documentation to the following function that includes a description, @param, @returns, and an @example with a JavaScript code block:

1
function getFullName(firstName, lastName) {
2
  return `${firstName} ${lastName}`;
3
}

Exercise 5: Optional Parameters

Add JSDoc documentation to the following function. Note that the greeting parameter has a default value and should be documented as optional with its default:

1
function createGreeting(name, greeting = "Hello") {
2
  return `${greeting}, ${name}!`;
3
}

Exercise 6: Custom Types with @typedef

Create a @typedef for a Product type that has name (string), price (number), and inStock (boolean) properties. Then add JSDoc documentation to the following function using your custom type:

1
function formatProduct(product) {
2
  const status = product.inStock ? "In Stock" : "Out of Stock";
3
  return `${product.name} - $${product.price} (${status})`;
4
}

Exercise 7: Complex Objects

Add JSDoc documentation to the following function using dot notation to document the object parameter's properties:

1
function createUserProfile(options) {
2
  return {
3
    username: options.username,
4
    email: options.email,
5
    age: options.age,
6
    createdAt: new Date(),
7
  };
8
}

Exercise 8: React Component

Add JSDoc documentation to the following React component, including a description, documented props, and an @example:

1
function ProductCard({ title, price, imageUrl, onAddToCart }) {
2
  return (
3
    <div className="product-card">
4
      <img src={imageUrl} alt={title} />
5
      <h3>{title}</h3>
6
      <p>${price}</p>
7
      <button onClick={onAddToCart}>Add to Cart</button>
8
    </div>
9
  );
10
}

Exercise 9: Generate Documentation

Using the functions you documented in the previous exercises:

1. Install JSDoc as a dev dependency
2. Create a conf.json configuration file
3. Add a docs script to your package.json
4. Generate the HTML documentation and view it in your browser

Exercise Solutions

1
/**
2
 * Greets a user by their name
3
 * @param {string} name The name of the user to greet
4
 * @returns {string} A greeting message
5
 */
6
function greetUser(name) {
7
  return `Hello, ${name}!`;
8
}

1
/**
2
 * Calculates the area of a rectangle
3
 * @param {number} width The width of the rectangle
4
 * @param {number} height The height of the rectangle
5
 * @returns {number} The area of the rectangle
6
 */
7
function calculateArea(width, height) {
8
  return width * height;
9
}

1
/**
2
 * Converts a string to uppercase
3
 * @param {string} text The text to convert
4
 * @returns {string} The text in uppercase
5
 */
6
function convertToUpperCase(text) {
7
  return text.toUpperCase();
8
}

1
/**
2
 * Combines first and last name into a full name
3
 * @param {string} firstName The person's first name
4
 * @param {string} lastName The person's last name
5
 * @returns {string} The combined full name
6
 * @example
7
 * ```js
8
 * const fullName = getFullName("John", "Doe");
9
 * console.log(fullName); // "John Doe"
10
 * ```
11
 */
12
function getFullName(firstName, lastName) {
13
  return `${firstName} ${lastName}`;
14
}

1
/**
2
 * Creates a greeting message with a customizable greeting word
3
 * @param {string} name The name of the person to greet
4
 * @param {string} [greeting="Hello"] The greeting word to use
5
 * @returns {string} The complete greeting message
6
 */
7
function createGreeting(name, greeting = "Hello") {
8
  return `${greeting}, ${name}!`;
9
}

1
/**
2
 * Represents a product in the store
3
 * @typedef {Object} Product
4
 * @property {string} name The product name
5
 * @property {number} price The product price in dollars
6
 * @property {boolean} inStock Whether the product is currently in stock
7
 */
8

9
/**
10
 * Formats a product for display
11
 * @param {Product} product The product to format
12
 * @returns {string} A formatted string showing product details
13
 * @example
14
 * ```js
15
 * const product = { name: "Laptop", price: 999, inStock: true };
16
 * const formatted = formatProduct(product);
17
 * console.log(formatted); // "Laptop - $999 (In Stock)"
18
 * ```
19
 */
20
function formatProduct(product) {
21
  const status = product.inStock ? "In Stock" : "Out of Stock";
22
  return `${product.name} - $${product.price} (${status})`;
23
}

1
/**
2
 * Creates a user profile object with timestamps
3
 * @param {Object} options The user profile options
4
 * @param {string} options.username The user's chosen username
5
 * @param {string} options.email The user's email address
6
 * @param {number} options.age The user's age in years
7
 * @returns {Object} The complete user profile with creation timestamp
8
 */
9
function createUserProfile(options) {
10
  return {
11
    username: options.username,
12
    email: options.email,
13
    age: options.age,
14
    createdAt: new Date(),
15
  };
16
}

1
/**
2
 * Props for the ProductCard component
3
 * @typedef {Object} ProductCardProps
4
 * @property {string} title The product title
5
 * @property {number} price The product price in dollars
6
 * @property {string} imageUrl URL to the product image
7
 * @property {Function} onAddToCart Callback function when add to cart is clicked
8
 */
9

10
/**
11
 * Displays a product card with image, title, price, and add to cart button
12
 * @param {ProductCardProps} props Component props
13
 * @example
14
 * ```jsx
15
 * <ProductCard
16
 *   title="Wireless Mouse"
17
 *   price={29.99}
18
 *   imageUrl="/images/mouse.jpg"
19
 *   onAddToCart={() => handleAddToCart(productId)}
20
 * />
21
 * ```
22
 */
23
function ProductCard({ title, price, imageUrl, onAddToCart }) {
24
  return (
25
    <div className="product-card">
26
      <img src={imageUrl} alt={title} />
27
      <h3>{title}</h3>
28
      <p>${price}</p>
29
      <button onClick={onAddToCart}>Add to Cart</button>
30
    </div>
31
  );
32
}

1
npm i jsdoc --save-dev

{
  "source": {
    "include": ["."],
    "exclude": ["node_modules/"]
  }
}

{
  "scripts": {
    "docs": "jsdoc -c ./conf.json -r"
  }
}

1
npm run docs

Additional Resources

• JSDoc Official Documentation
• JSDoc Cheatsheet