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

unravel_tom

于 2024-07-29 01:55:36 发布

阅读量323

点赞数 24

分类专栏： Web3 文章标签： javascript 前端开发语言

本文链接：https://blog.csdn.net/unravel_tom/article/details/140759331

版权

Web3 专栏收录该内容

2 篇文章 0 订阅

订阅专栏

JSDoc：JavaScript 代码的 "说明书"

前言

想象一下，你正在阅读一本没有任何章节标题、段落说明或脚注的厚重小说。感觉如何？可能会很困惑，对吧？代码也是一样的。没有适当注释的代码就像是没有任何指引的迷宫。那么，让我们来探讨一下为什么注释，特别是文档注释，对于编程如此重要。

编写清晰的文档注释就像是为你的代码创建一份详细的使用手册。它不仅帮助他人理解和使用你的代码，也能让未来的你感谢现在的自己的周到考虑。记住，好的代码自己解释做什么，好的注释解释为什么。而好的文档注释则告诉人们如何正确地使用你的代码。

注释文档

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

想象你正在阅读一个复杂的魔术技巧说明。如果没有解释，你可能会感到困惑。代码注释就像魔术师的解释，帮助其他人（包括未来的你）理解代码在做什么。它们可以：

解释复杂的逻辑
提供背景信息
警告潜在的陷阱
解释为什么选择了特定的实现方式

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

想象你正在阅读一本食谱。普通注释就像是旁边的小贴士，比如"小心别把糖放太多"。而文档注释则更像是每个菜谱开头的详细说明，包括所需材料、预期成果，以及可能的变化。

普通注释：

通常是针对代码的特定行或小块
解释"如何"和"为什么"
使用 // 或 /* */ 格式

文档注释：

通常位于函数、类或模块的开头
描述"是什么"、"做什么"和"如何使用"
使用特定格式（如 JSDoc 中的 /** */）
可以被工具自动提取生成文档

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

想象你买了一个新玩具，但没有说明书。你可能最终会弄明白如何使用它，但过程可能会很痛苦。文档注释就像是代码的说明书，它们：

加速学习曲线：新队员可以更快地理解和使用代码。
减少错误：清晰的使用说明可以防止误用。
提高效率：减少了解释代码功能的时间。
支持维护：当需要更新代码时，好的文档注释是无价的。
自动生成文档：许多工具可以从这些注释自动创建API文档。

Q4: 如何写好文档注释？

想象你正在为一个朋友写一份操作指南。你会包括哪些信息？好的文档注释应该：

功能描述：这段代码是做什么的？
参数说明：需要什么"原料"（输入）？
返回值：会得到什么"成品"（输出）？
例子：如何使用这段代码？
注意事项：有什么需要特别注意的吗？

例如：

在 VSCode 中使用这两个函数版本时，你会注意到以下有趣的现象：

无注释版本：当你调用 calculateTotal() 时，VSCode 只会显示基本的函数签名。

//计算购物车的总价
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 注释呢？你会发现，这个小小的习惯可以给你的编程生活带来大大的改变！

unravel_tom

关注

24
点赞
踩
9

收藏

觉得还不错? 一键收藏
0
评论
JS：JSDoc 构建属于代码的说明书

想象一下，你正在阅读一本没有任何章节标题、段落说明或脚注的厚重小说。感觉如何？可能会很困惑，对吧？代码也是一样的。没有适当注释的代码就像是没有任何指引的迷宫。那么，让我们来探讨一下为什么注释，特别是文档注释，对于编程如此重要。编写清晰的文档注释就像是为你的代码创建一份详细的使用手册。它不仅帮助他人理解和使用你的代码，也能让未来的你感谢现在的自己的周到考虑。记住，好的代码自己解释做什么，好的注释解释为什么。而好的文档注释则告诉人们如何正确地使用你的代码。
复制链接

扫一扫

专栏目录