在前端开发中，写好注释是非常重要的。这不仅可以帮助他人更好地理解代码，还可以提高代码可维护性和可读性。JSDoc是一种用于JavaScript代码注释的标准格式，它能够生成文档和类型检查等功能，使注释更加丰富和有意义。
为什么需要使用 JSDoc？
在项目开发过程中，我们经常需要阅读或修改别人的代码。此时，如何快速了解代码的作用、输入参数和输出结果就变得尤为关键。而JSDoc能够通过规范化注释的方式，提供清晰明确的代码说明，让读者更容易理解。
同时，在代码开发过程中，我们也会遇到需要判断变量类型或给函数传递正确的参数等问题。使用JSDoc可以在编码过程中实现类型检查和自动补全，避免出错，提高开发效率。
JSDoc 基本语法
安装和配置
在VSCode中，可以安装JSDoc插件来支持JSDoc注释。或者使用命令行工具TypeDoc 。
注释格式
下面是一个简单的JSDoc注释样例：
-- -------------------- ---- ------- --- - ------- - ------ -------- ---- - ---- - ------ -------- ---- - ---- - -------- -------- ---- -- -------- --------- ----- - ------ ---- - ----- -
在这个样例中，我们可以看到JSDoc注释有以下几个部分：
/**开头的多行注释格式。@param参数说明。@returns返回值说明。
注释内容
在JSDoc注释中，除了基本的参数和返回值说明，还可以使用其他标记来提供更加详细的注释信息。下面是一些常用的注释标记：
@typedef
定义一个类型别名，方便后续使用。
-- -------------------- ---- ------- --- - ---- - -------- -------- -------- - --------- -------- ---- - --- - --------- -------- ----- - -- - --------- -------- --- - -- -- --- - ------ - ------ -------- -- - ---- - -------- ---------- ------ -- -------- --------------- - -- --- -
在此样例中，我们定义了一个名称为UserInfo的类型别名，其中包含了name、email和age三个属性。在getUserInfo函数中，我们使用了@returns标记来指明返回值的类型为UserInfo。
@enum
定义一个枚举类型。
-- -------------------- ---- ------- --- - ---- - ----- -------- -- ----- ------ - - ---- ------ ------ -------- ----- ------ -
在此样例中，我们定义了一个名称为Colors的枚举类型，其中包含了三个值：Red、Green和Blue。
@callback
定义一个回调函数类型。
-- -------------------- ---- ------- --- - ---- - --------- --------------- - ------ ------- ----- - ---- - ------ -------- ------ - ---- -- --- - ---- - ------ -------- --- - ----- - ------ ----------------- -------- - ---- -- -------- ------------ --------- - -- --- -
在此样例中，我们定义了一个名称为RequestCallback的回调函数类型，其中有一个参数error表示错误信息，另一个参数result表示成功返回的数据。在request函数中，我们使用了@param标记来指明回调函数的类型为RequestCallback。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/13417