JS：JSDoc 构建属于代码的说明书

//计算购物车的总价
function calculateTotal(items, tax, discount) {
  let sum = items.reduce((acc, item) => acc + item.price * item.quantity, 0);
  sum += sum * tax;
  return sum * (1 - discount);
}

有注释版本：当你调用 calculateTotal() 时，VSCode 会显示详细的参数说明和返回值信息。

/**
* 计算购物车的总价。
* @param {Array<{price: number, quantity: number}>} items - 购物车中的商品数组。
* @param {number} tax - 税率，以小数形式表示（例如，0.1 表示 10% 的税）。
* @param {number} discount - 折扣率，以小数形式表示（例如，0.2 表示 20% 的折扣）。
* @returns {number} 应付总额。
* @throws {Error} 如果税率或折扣率无效。
*/
function calculateTotal(items, tax, discount) {
  if (tax < 0 || tax > 1) throw new Error('无效的税率');
  if (discount < 0 || discount > 1) throw new Error('无效的折扣率');

  // 计算商品总价
  let sum = items.reduce((acc, item) => acc + item.price * item.quantity, 0);

  // 加税
  sum += sum * tax;

  // 应用折扣
  return sum * (1 - discount);
}

JSDoc：JavaScript 代码的 "说明书"

你有没有遇到过这样的情况：几个月前写的代码现在看起来像天书？或者新加入团队的同事看着你的代码一脸茫然？别担心，JSDoc 就是为解决这些问题而生的！

什么是 JSDoc？

JSDoc 就像是给你的 JavaScript 代码穿上一件带有详细说明的 T 恤。它使用特殊格式的注释来描述你的代码，不仅人类可以读懂，计算机也能理解。

想象你在组装一个复杂的玩具，JSDoc 就是那份告诉你每个零件用途的说明书。

JSDoc 能做什么？

自动生成文档：就像魔法一样，JSDoc 可以把你的注释变成漂亮的 HTML 文档。
提供智能提示：在 VSCode 等编辑器中，JSDoc 注释可以让你在使用函数时获得详细的参数提示。
增强代码可读性：为团队成员（包括未来的你）提供清晰的代码解释。
支持类型检查：即使在普通的 JavaScript 中，也能享受到类似 TypeScript 的类型检查benefits。

如何使用 JSDoc？

使用 JSDoc 就像给你的代码写一份小简历。这里有一个简单的例子：

/**
 * Hello "Name"
 *
 * @param {string} name person/thing you want to say hello to.
 * @returns {string} Hello + name 
 */
function hello(name) {
  return "Hello "+name +"!";
}

看，是不是很简单？你只需要在函数上方添加一些特殊的注释，解释这个函数是做什么的，需要什么参数，会返回什么。

JSDoc 的常用标签

官方文档：块级标签 | JSDoc中文文档 | JSDoc中文网

JSDoc 使用一系列特殊的标签来描述代码。这些标签就像是一套特殊的词汇，用来精确描述你的代码：（记住常用的就行了，绝大数标签都是无用的）

@param: 描述函数参数
@returns: 描述函数返回值
@throws: 描述可能抛出的错误
@example: 提供使用示例
@type: 指定变量类型
@typedef: 定义自定义类型
@class: 描述一个类
@constructor: 标记构造函数
@see: 引用其他文档
@todo: 标记待完成的任务

如何开始使用 JSDoc？

安装 JSDoc：
```
jsdoc yourfile.js
```
为你的代码添加 JSDoc 注释。
运行 JSDoc 生成文档，此时在你的项目中会出现out的文件夹，我们点开找到 global.html即可
```
jsdoc yourfile.js
```
惊叹于自动生成的漂亮文档！

out目录简介

out/
│
├── fonts/          //包含文档使用的字体文件。
│   └── (字体文件)
│
├── scripts/        //包含使文档交互式的JavaScript文件。
│   └── (JavaScript文件)
│
├── styles/         //包含文档的CSS样式表
│   └── (CSS文件)
│
├── global.html     //包含全局变量、函数和命名空间的文档。
├── index.html      //文档的主页，通常包含项目概述和导航。
└── test.js.html    //你的原始JavaScript文件（test.js）的带注释版本

这种结构使得你可以轻松地将整个'out'文件夹部署到web服务器上，为你的项目提供在线文档。它不仅对开发团队有帮助，对可能使用你的代码的其他开发者也很有用。

使用 JSDoc 的小贴士

保持简洁：注释应该清晰但不冗长。
保持一致：在整个项目中使用统一的注释风格。
及时更新：当代码变更时，记得更新相应的注释。
结合 IDE：利用 VSCode 等编辑器的 JSDoc 支持功能。

结语

JSDoc 就像是给你的代码配了一个24/7全天候的解说员。它不仅让你的代码更容易理解和维护，还能提高整个开发过程的效率。所以，何不现在就开始尝试在你的下一个函数中加入 JSDoc 注释呢？你会发现，这个小小的习惯可以给你的编程生活带来大大的改变！

标签：代码,JS,注释,构建,使用,文档,sum,JSDoc
From： https://blog.csdn.net/unravel_tom/article/details/140759331

JS：JSDoc 构建属于代码的说明书

前言

注释文档

Q1: 为什么我们需要在代码中添加注释？

Q2: 普通注释和文档注释有什么不同？

Q3: 为什么文档注释如此重要？

Q4: 如何写好文档注释？