JSDoc 3 入门

入门

JSDoc 3 是 JavaScript 的 API 文档生成器，类似于 Javadoc 或 phpDocumentor。你可以将文档注释直接添加到源代码中，与代码本身并列。JSDoc 工具将扫描你的源代码并为你生成一个 HTML 文档网站。

向你的代码中添加文档注释

JSDoc 的目的是记录你的 JavaScript 应用程序或库的 API。我们假设你希望记录模块、命名空间、类、方法、方法参数等内容。

JSDoc 注释通常应放置在要记录的代码之前。每个注释都必须以 /** 序列开头，以便 JSDoc 解析器识别。以 /*、/*** 或超过 3 个星号开头的注释将被忽略。这是一个允许你禁止注释块解析的功能。

最简单的文档只是一个描述

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

添加描述很简单——只需在文档注释中输入你想要的描述即可。

可以使用特殊的“JSDoc 标记”来提供更多信息。例如，如果函数是类的构造函数，你可以通过添加 @constructor 标记来指示这一点。

使用 JSDoc 标记来描述你的代码

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

可以使用更多标记来添加更多信息。请参阅主页，了解 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) {
}

生成网站

代码添加注释后，你可以使用 JSDoc 3 工具从源文件中生成一个 HTML 网站。

默认情况下，JSDoc 使用内置的“默认”模板将文档转换为 HTML。你可以根据自己的需要编辑此模板，或者创建全新的模板（如果你愿意）。

在命令行上运行文档生成器

jsdoc book.js

此命令将在当前工作目录中创建一个名为 out/ 的目录。在该目录中，你会找到生成的 HTML 页面。