JSDoc

JSDoc 是许多代码库中使用的一种流行的内联文档方法。

编写 JSDoc 是为了增强代码的可读性，以及方便导出 API 文档。

为什么要使用 JSDoc？

JSDoc 是 DocBlock 的 JavaScript 实现，DocBlock 是一种用于各种编程语言（包括 PHP、Ruby 和 Python）的文档方法。

它提供了一种一致且可识别的文档方法。还有几个工具可以根据 JSDoc 注释自动生成文档。

将文档注释添加到您的代码

JSDoc 的目的是记录您的 JavaScript 应用程序或库的 API。假设您需要为模块、命名空间、类、方法和方法参数等内容添加注释。

最简单的方法是创建一个带有两个前导星号 ( /**) 的注释，以及对函数功能的描述。

/**
 * 将两个数字相加
 */
function add(num1, num2) {
  return num1 + num2
}

添加描述很简单，只需在文档注释中键入您想要的描述即可。

特殊的 JSDoc 标签可用于提供更多信息。最常用的是 @param，它描述了一个函数参数，和 @return，它描述了返回的内容。

使用 JSDoc 标签来描述您的代码：

/**
 * 将两个数字相加
 * @param  {Number} num1 要添加的第一个数字
 * @param  {Number} num2 要添加的第二个数字
 * @return {Number}      总数
 */
function add(num1, num2) {
  return num1 + num2
}

更多标签可用于添加更多信息。有关 JSDoc 的完整标签列表，请参阅 Block Tags。

生成网站

添加代码注释后，您可以使用 JSDoc 工具从源文件生成 HTML 网站。

默认情况下，JSDoc 使用内置的默认模板将文档转换为 HTML。您可以编辑此模板以满足您自己的需求，或者创建一个全新的模板。

在命令行上运行文档生成器：

npx jsdoc index.js

此命令将在当前工作目录中创建以 /out 命名的目录。在该目录中，您将找到生成的 HTML 页面。

以上述的代码为例，生成的页面如下：

JSDoc 生成文档

最后

我相信，很多开发人员都不喜欢写注释。

很多开发人员都追求代码的自我描述性，代码的目的非常明显，不需要文档。

对你来说显而易见的东西可能对阅读你代码的其他人来说并不明显。适当的添加一些注释，可以帮助他们更快、更容易地工作。

好的文档不仅仅描述发生了什么，还描述了为什么要这样做。一年后，当你去看一段时间没有接触过的代码时，你会忘记这些内容。

更多资料

Document This 是一个 VS Code 扩展，可以自动为 TypeScript 和 JavaScript 文件生成详细的 JSDoc 注释。

另一个不错的 JSDoc 注释扩展 — Add jsdoc comments

演示

本文首发 blog，如果喜欢或者有所启发，欢迎 Star，对作者也是一种鼓励。