JSDoc 3 入门

入门

¥Getting started

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

¥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 的目的是记录 JavaScript 应用或库的 API。假设你需要记录模块、命名空间、类、方法、方法参数等内容。

¥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 注释通常应紧接在正在记录的代码之前放置。每个注释必须以 /** 序列开头才能被 JSDoc 解析器识别。以 /*、/*** 或超过 3 星开头的评论将被忽略。该功能允许你抑制注释块的解析。

¥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.

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

¥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) {
}

可以使用更多标签来添加更多信息。请参阅 主页 以获取 JSDoc 3 识别的标签的完整列表。

¥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

对代码进行注释后，你可以使用 JSDoc 3 工具从源文件生成 HTML 网站。

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

默认情况下，JSDoc 使用内置的 "default" 模板将文档转换为 HTML。你可以编辑此模板以满足你自己的需求，或者根据你的喜好创建一个全新的模板。

¥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

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

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