To use JSDoc, you'll need to write specially-formatted comments above your functions, classes, and other code elements. These comments begin with
/** and end with
*/. Within these comments, you can use JSDoc-specific tags to further describe your code. Let's start with a simple example:
In this example, we've written a simple
add() function and provided a JSDoc comment above it. The comment begins with a brief description of the function, followed by specific JSDoc tags:
@param: Describes an input parameter for the function. It includes the type (
number, in this case), the parameter's name (
a), and a description.
@returns: Describes the return value of the function. It includes the type (
number) and a description.
Common JSDoc Tags
@constructor: Indicates that a function is a constructor for a class.
@class: Indicates that the function is a class (useful if you're not using the
@property: Describes a property of a class or object.
@extends: Indicates that a class or object inherits from another class or object.
@private: Indicates that a member is private and should not be used outside of its containing class.
@public: Indicates that a member is public and can be used freely.
@deprecated: Indicates that a function, method, or property is deprecated and should not be used.
JSDoc is also great at documenting classes and their properties and methods. Let's take a look at an example:
In this example, we've documented a
Point class with a constructor and a
distance() method. We use the
@constructor tag to indicate that the
Point function is a class constructor, and the
@returns tags are used similarly to the previous example.
Once you've added JSDoc comments to your code, you can use the JSDoc command-line tool to generate an HTML documentation site. Install the tool using
This will generate an
out folder containing the HTML documentation site, which you can open in your browser to view the generated documentation.
To add JSDoc annotations, you'll use specially formatted comments that start with
/** followed by your annotations on each line using an asterisk
*. Here's an example:
What are some common JSDoc tags and their syntax?
There are many JSDoc tags available, but some common ones include:
@param: Documents a function parameter with its type, name, and description.
@returns: Documents the return value of a function with its type and description.
@type: Documents the type of a variable, property, or object.
@namespace: Documents a collection of related methods and properties.
@module: Documents a module with a description.
You'll need to install the JSDoc tool using npm, like this:
Then, to generate the HTML documentation, run the following command:
This will generate an
out directory containing the HTML documentation.
Can I customize the appearance of my generated documentation?
Yes, you can customize the appearance of your generated documentation by using templates. There are numerous JSDoc templates available, or you can create your own. To use a template, install it via npm and then pass the
--template option when running the
jsdoc command, like this: