js - js JSDoc - 《public》

JSDoc 是一个用于 JS 的文档生成器工具。它读取与 JS 文件中的特定格式注释相关的源代码，并生成一个整洁、格式化的文档页面，通常是 HTML 格式。这些注释通常包含关于函数、类、模块、参数、返回值和其他重要信息的描述。

以下是 JSDoc 的一些关键特点：

注释风格：JSDoc 注释以 /** 开头（这与普通的多行 JS 注释 /* 不同），然后每行都以 * 开始，并最终以 */ 结束。
标签系统：JSDoc 使用一系列的“标签”（如 @param, @returns, @class 等）来指示注释中的特定部分。这些标签帮助 JSDoc 解析注释内容并将其格式化为文档。
类型标注：在注释中，开发者可以使用 {} 来指定特定变量或返回值的预期类型，例如 {number} 或 {string}。
支持自定义模板：开发者可以使用自定义模板来决定生成文档的外观和布局。
支持插件：JSDoc 支持使用插件，从而扩展其功能或增加新的标签。

示例：

/**
 * 计算两个数字的和。
 *
 * @function
 * @param {number} a - 第一个数。
 * @param {number} b - 第二个数。
 * @returns {number} 两个数的和。
 */
function add(a, b) {
    return a + b;
}

上述示例展示了一个使用 JSDoc 注释的函数。其中：

@function 标签表明这是一个函数的描述。
@param 标签描述了函数的参数，并为每个参数指定了预期的类型。
@returns 标签描述了函数的返回值及其类型。

当运行 JSDoc 工具时，上述注释会被解析，并生成一个描述 add 函数的文档页面。

总的来说，JSDoc 提供了一种方法，使得开发者能够在代码中直接编写文档，从而使代码更具有描述性，并能自动生成详细的 API 文档。