javascript

Documentation Comments (JSDoc)

Learn JSDoc comments to document JavaScript code. Understand how to use tags like @param, @returns, and @type to make your code clearer for yourself and others.

10 min read 8 sections Tutorial

JSDoc comments are special notes you add to your JavaScript code. They help you explain what your code does, what inputs it needs, and what it gives back. These comments make your code much easier for other people (and your future self!) to understand.

Documentation Comments (JSDoc)

JSDoc comments are a way to add detailed explanations to your JavaScript code. Think of them as instruction manuals for your functions, variables, and classes. They tell developers how to use your code correctly.

These comments are not just for humans. Programming tools and code editors like VS Code can read JSDoc. They use this information to give you helpful hints, auto-completion, and warnings as you type. This makes coding faster and reduces mistakes.

What is JSDoc?

JSDoc is a markup language used within special comments (/** ... */) in JavaScript files to describe code elements like functions, parameters, return values, and classes.

Clearer Code

JSDoc explains complex parts of your code, making it simple for anyone to understand its purpose and how to use it.

IDE Support

Code editors use JSDoc to provide smart auto-completion and helpful hints directly as you write code.

Auto-Generated Docs

Special tools can read JSDoc comments and create beautiful HTML documentation websites from your code.

Fewer Bugs

When code is well-documented, developers make fewer assumptions and avoid common errors, leading to more robust software.

What are JSDoc Comments?

Getting Started

What are JSDoc Comments?

JSDoc comments start with /** (two asterisks) and end with */. This is different from regular comments which start with /* (one asterisk) or //. The extra asterisk tells tools that this is a special documentation comment.

Inside these comments, you use special words called tags. Tags start with an @ symbol. Each tag describes a different part of your code, like @param for a function's input or @returns for what a function gives back.

javascriptA simple function with JSDoc

1/**
2 * Adds two numbers together and returns their sum.
3 * This is a description of what the function does.
4 *
5 * @param {number} num1 - The first number to add.
6 * @param {number} num2 - The second number to add.
7 * @returns {number} The sum of num1 and num2.
8 */
9function addNumbers(num1, num2) {
10  return num1 + num2;
11}
12
13// When you hover over 'addNumbers' in your editor, you'll see this JSDoc!
14const result = addNumbers(5, 3);
15console.log(result); // Output: 8

Don't forget the second asterisk!

If your comment starts with /* (one asterisk) instead of /** (two asterisks), it's just a regular comment. JSDoc tools will ignore it. Always use /** for JSDoc to work.

Common JSDoc Tags

JSDoc has many tags, but a few are used most often. The main ones help describe function inputs, outputs, and the types of data involved. Understanding these core tags lets you document almost any function effectively.

Each tag has a specific format. For example, @param needs to know the data type, the name of the parameter, and a description. The data type is written inside curly braces {}.

javascriptUsing common JSDoc tags

1/**
2 * Calculates the area of a rectangle.
3 *
4 * @param {number} width - The width of the rectangle.
5 * @param {number} height - The height of the rectangle.
6 * @returns {number} The calculated area.
7 * @example
8 * // Example usage:
9 * const area = calculateRectangleArea(10, 5);
10 * console.log(area); // 50
11 */
12function calculateRectangleArea(width, height) {
13  return width * height;
14}
15
16/**
17 * Stores the name of the application.
18 * @type {string}
19 */
20const appName = "My Awesome App";
21
22console.log(calculateRectangleArea(7, 4)); // Output: 28
23console.log(appName); // Output: My Awesome App

✗ BadWithout JSDoc

function createUser(name, age, isActive) {
  return { name, age, isActive };
}

✓ GoodWith JSDoc

/**
 * Creates a new user object.
 * @param {string} name - The user's name.
 * @param {number} age - The user's age.
 * @param {boolean} isActive - True if the user is active, false otherwise.
 * @returns {{name: string, age: number, isActive: boolean}} The new user object.
 */
function createUser(name, age, isActive) {
  return { name, age, isActive };
}

Documenting Different Code Structures

JSDoc is not just for functions. You can use it to describe almost any part of your JavaScript code. This includes variables, objects, and even entire classes. The tags you use might change slightly depending on what you are documenting.

For example, documenting a class involves describing the class itself, its constructor, and its methods. Each part gets its own JSDoc block to keep things clear and organized.

Documenting a Function

Documenting a Class

Documenting a Function

/**
 * Greets a user by their name.
 * @param {string} name - The user's name.
 * @returns {string} A greeting message.
 */
function greetUser(name) {
  return `Hello, ${name}!`;
}

console.log(greetUser('Alice'));

Documenting a Class

/**
 * Represents a person with a name and age.
 * @class
 */
class Person {
  /**
   * Creates an instance of Person.
   * @param {string} name - The person's name.
   * @param {number} age - The person's age.
   */
  constructor(name, age) {
    /** @type {string} */
    this.name = name;
    /** @type {number} */
    this.age = age;
  }

  /**
   * Returns a greeting message from the person.
   * @returns {string} A greeting.
   */
  sayHello() {
    return `Hi, I'm ${this.name} and I'm ${this.age} years old.`;
  }
}

const bob = new Person('Bob', 30);
console.log(bob.sayHello());

/**
 * Greets a user by their name.
 * @param {string} name - The user's name.
 * @returns {string} A greeting message.
 */
function greetUser(name) {
  return `Hello, ${name}!`;
}

console.log(greetUser('Alice'));

/**
 * Represents a person with a name and age.
 * @class
 */
class Person {
  /**
   * Creates an instance of Person.
   * @param {string} name - The person's name.
   * @param {number} age - The person's age.
   */
  constructor(name, age) {
    /** @type {string} */
    this.name = name;
    /** @type {number} */
    this.age = age;
  }

  /**
   * Returns a greeting message from the person.
   * @returns {string} A greeting.
   */
  sayHello() {
    return `Hi, I'm ${this.name} and I'm ${this.age} years old.`;
  }
}

const bob = new Person('Bob', 30);
console.log(bob.sayHello());

Document Public APIs

Focus on documenting the parts of your code that other developers will use. These are often called 'public APIs'. Internal helper functions might need less detailed JSDoc, or just regular comments.

Generating Documentation and IDE Support

One of the biggest benefits of JSDoc is how it integrates with development tools. Your code editor can read JSDoc comments and use them to help you write code. This means you get instant feedback and information about functions.

Beyond editor hints, you can also use a special program called jsdoc to turn your comments into a full website. This website will list all your functions, classes, and variables with their descriptions, parameters, and examples. It is a professional way to share how your code works.

Write JSDoc in your code

Add /** ... */ comments above your functions, classes, and variables. Use tags like @param, @returns, and @type.

javascriptWrite JSDoc in your code

1/**
2 * Multiplies two numbers.
3 * @param {number} a - First factor.
4 * @param {number} b - Second factor.
5 * @returns {number} Product of a and b.
6 */
7function multiply(a, b) {
8  return a * b;
9}

See IDE hints

Hover your mouse over multiply in your code editor (like VS Code). You will see a pop-up with the description, parameters, and return type from your JSDoc. This is a huge time-saver!

javascriptSee IDE hints

1// Hover over 'multiply' here:
2const product = multiply(10, 5);

Generate HTML documentation

Install the JSDoc tool globally (npm install -g jsdoc). Then, run jsdoc your-file.js in your terminal. This creates an out folder with HTML files — a complete documentation website for your project.

bashGenerate HTML documentation

1npm install -g jsdoc
2jsdoc my_project_folder/

Outdated JSDoc is worse than no JSDoc

If you change your code but forget to update the JSDoc, it can mislead other developers. Incorrect documentation can cause confusion and bugs. Always keep your JSDoc comments accurate and up-to-date with your code changes.

JSDoc Tag Reference

Tag	Purpose	Example Usage	Applies To
@param	Describes a function parameter (input).	`@param {string} name - User's name.`	Functions
@returns	Describes the value a function gives back.	`@returns {boolean} True if successful.`	Functions
@type	Specifies the data type of a variable or property.	`@type {number}`	Variables, properties
@typedef	Defines a custom data type (like a complex object structure).	`@typedef {object} User`	Anywhere
@example	Provides a code example of how to use the documented item.	`@example const x = add(1,2);`	Functions, classes
@class	Marks a function or variable as a constructor for a class.	`@class MyClass`	Classes
@property	Describes a property of an object or class.	`@property {string} name - Person's name.`	Objects, classes

Test Your Knowledge

Quick Check

Which special comment syntax marks a block as a JSDoc comment?

Quick Check

What is the primary purpose of the @param tag in JSDoc?

Quick Check

What benefit does JSDoc provide in a code editor like VS Code?

Quick Check

Which JSDoc tag would you use to define a custom object type?

Quick Reference

Pro Tips

1JSDoc Comments — start with /** and end with */ to be recognized by tools.
2Tags — special words starting with @ (e.g., @param, @returns) that describe code elements.
3@param — describes a function's input parameter, including its {type}, name, and description.
4@returns — describes the {type} and description of the value a function gives back.
5@type — specifies the {type} of a variable or property.
6@typedef — defines a custom object or data structure type for reuse.
7@example — provides runnable code snippets to show how to use the documented item.
8IDE Support — JSDoc enables smart auto-completion, hover information, and type checking in code editors.
9Documentation Generation — tools like jsdoc can create professional HTML documentation websites from your comments.
10Keep it Updated — always update JSDoc comments when your code changes to prevent misleading information.

TypeScript Basics

Explore TypeScript for even stronger type safety and more robust code.

Command Line Tools

Learn how to use command-line tools like jsdoc to automate tasks.

Clean Code Principles

Understand general best practices for writing code that is easy to read and maintain.

Linting and Formatting

Discover tools like ESLint and Prettier to enforce consistent code style and find potential issues.

You've mastered JSDoc comments!

You now understand how to use JSDoc comments to document your JavaScript code. You can describe functions, parameters, return values, and even classes, making your projects clearer and more professional. This skill is vital for collaborating with others and maintaining large codebases.

Try it in the Javascript Compiler

Run and experiment with Javascript code right in your browser — no setup needed.

Open Javascript Compiler

Continue Learning

Previous Next