JSDoc

Posted on

这个是JSDoc 官方文档，我这边简单做一些介绍。

介绍

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

向代码中添加文档注释

JSDoc 的目的是记录 JavaScript 应用程序或库的 API。假设您想要记录诸如模块、名称空间、类、方法、方法参数等内容。

JSDoc 注释通常应该放在记录代码之前。为了被 JSDoc 解析器识别，每个注释必须以 /** 序列开头。以 /、/**开头或超过 3 颗星的注释将被忽略。这个特性用于控制解析注释块的功能。

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

1
2
3
4
5
6
7
/**
 * 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 页面。