开始使用 JSDoc 3

目录

• 快速开始
• Adding documentation comments to your code
• Generating a website

快速开始

JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. You add documentation comments directly to your source code, right alongside the code itself. The JSDoc tool will scan your source code and generate an HTML documentation website for you.

Adding documentation comments to your code

JSDoc's purpose is to document the API of your JavaScript application or library. It is assumed that you will want to document things like modules, namespaces, classes, methods, method parameters, and so on.

JSDoc comments should generally be placed immediately before the code being documented. Each comment must start with a /** sequence in order to be recognized by the JSDoc parser. Comments beginning with /*, /***, or more than 3 stars will be ignored. This is a feature to allow you to suppress parsing of comment blocks.

/** This is a description of the foo function. */
function foo() {
}

Adding a description is simple—just type the description you want in the documentation comment.

Special "JSDoc tags" can be used to give more information. For example, if the function is a constructor for a class, you can indicate this by adding a @constructor tag.

/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {
}

More tags can be used to add more information. See the home page for a complete list of tags that are recognized by JSDoc 3.

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

Generating a website

Once your code is commented, you can use the JSDoc 3 tool to generate an HTML website from your source files.

By default, JSDoc uses the built-in "default" template to turn the documentation into HTML. You can edit this template to suit your own needs or create an entirely new template if that is what you prefer.

jsdoc book.js

This command will create a directory named out/ in the current working directory. Within that directory, you will find the generated HTML pages.