什么是 JSDoc
JSDoc 是一个 JavaScript 的文档化工具。它通过读取代码注释来生成文档，使得代码中的函数、变量、参数等等语义信息可以被自动提取出来，并生成可搜索可交互的 HTML 网页，以便让其他开发者更好地理解你的代码。
JSDoc 的注释写法基于 JSDoc 标准，使用 JSDoc 工具生成的文档具有标准化、易维护的特点，从而使代码的使用和维护更加简便。
JSDoc 的功能
JSDoc 集成了各种类型的注释标签，可以实现以下功能：
- 描述变量和函数的输入输出参数
- 标记函数的功能和目的
- 显示函数的参数默认值和类型
- 显示函数返回值的类型和含义
- 确认代码的使用案例和引用位置
- 提供代码嵌套结构和继承的视图
JSDoc 的安装和使用
JSDoc 支持全局安装和局部安装，可以通过 npm 命令来安装 JSDoc：
npm install -g jsdoc # 全局安装 npm install --save-dev jsdoc # 局部安装
安装完成后，可以在项目的根目录下创建一个 jsdoc.conf.json 配置文件：
// www.javascriptcn.com code example
{
"source": {
"include": ["./src"],
"exclude": [],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"plugins": [],
"recurseDepth": 10,
"opts": {
"destination": "./docs",
"encoding": "utf8",
"package": "./package.json",
"readme": "./README.md",
"template": "./node_modules/minami"
},
"templates": {
"systemName": "JSDoc example",
"footer": "",
"logo": "",
"navLinks": [],
"theme": "default",
"linenums": true,
"collapseSymbols": false,
"inverseNav": false
}
}其中，source 指定要生成文档的源代码目录；opts 指定文档生成的输出目录、编码、 package.json 和 README.md 的位置，以及使用的 HTML 模板。
在项目中，可以在代码中使用 JSDoc 注释，如下所示：
// www.javascriptcn.com code example
/**
* Adds two numbers.
* @param {number} num1 The first number to add.
* @param {number} num2 The second number to add.
* @returns {number} The sum of num1 and num2.
*/
function add(num1, num2) {
return num1 + num2;
}
在这个例子中，函数 add 的第一行是一个描述，后面的 @param，@returns 是注释标签，描述了函数接受的参数和返回值的类型。JSDoc 解释器会自动读取这些标签并生成相应的文档。
最后，使用下面的命令可以生成文档：
jsdoc -c jsdoc.conf.json
然后在浏览器中打开 docs/index.html 即可查看文档。
JSDoc 的示例
在下面的例子中，我们将实现一个简单的计算器。我们将使用 JSDoc 描述代码集成，使其具有更好的可读性和可维护性。
// www.javascriptcn.com code example
/**
* Calculator class
* @class
* @classdesc Implements basic arithmetic operations.
*/
class Calculator {
/**
* Adds two numbers.
* @param {number} a The first number to add.
* @param {number} b The second number to add.
* @returns {number} The sum of a and b.
* @example
* var calc = new Calculator();
* console.log(calc.add(4, 3)); // 7
*/
add(a, b) {
return a + b;
}
/**
* Subtracts two numbers.
* @param {number} a The first number to subtract.
* @param {number} b The second number to subtract.
* @returns {number} The difference of a and b.
* @example
* var calc = new Calculator();
* console.log(calc.sub(4, 3)); // 1
*/
sub(a, b) {
return a - b;
}
/**
* Multiplies two numbers.
* @param {number} a The first number to multiply.
* @param {number} b The second number to multiply.
* @returns {number} The product of a and b.
* @example
* var calc = new Calculator();
* console.log(calc.mul(4, 3)); // 12
*/
mul(a, b) {
return a * b;
}
/**
* Divides two numbers.
* @param {number} a The first number to divide.
* @param {number} b The second number to divide.
* @returns {number} The quotient of a and b.
* @example
* var calc = new Calculator();
* console.log(calc.div(4, 2)); // 2
* console.log(calc.div(4, 0)); // Infinity
*/
div(a, b) {
return a / b;
}
}在这个例子中，我们使用了 @class，@classdesc，@param，@returns 和 @example 等注释标签来生成文档。
在使用 JSDoc 时，通过良好的注释规范，可以使得我们的代码变得更加清晰、易读、易于维护。
对于前端开发人员来说，JSDoc 是必备的文档化工具，它可以大大提高代码的可读性和可维护性。我们可以通过 JSDoc 生成美观而且易于访问的文档，加速我们的开发流程，减少协作和沟通成本。 > 来源：[JavaScript中文网](https://www.javascriptcn.com/post/67d6b423a941bf7134c8be29) ，转载请注明来源 [https://www.javascriptcn.com/post/67d6b423a941bf7134c8be29](https://www.javascriptcn.com/post/67d6b423a941bf7134c8be29)