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.

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

/**
 * 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.