在JavaScript中，文档注释是一种特殊的注释格式，用于描述代码的功能、使用方法、参数、返回值等信息。文档注释通常使用特定的注释标记和结构来表示，并且可以通过工具解析生成文档。
在JavaScript中，常用的文档注释格式是使用 / 和 */ 括起来的多行注释。例如：
上面的代码段中，以 / 开始和以 */ 结束的多行注释就是文档注释。在注释的内容中，使用了一些特殊的标记来表示相关信息，比如 @param 表示参数，@returns 表示返回值。可以在这些标记后面添加具体的描述和类型信息。
编写的文档注释有助于、、、，。这是为了更好地组织和记录代码，并使其更易于理解和使用的最佳实践之一。
- ：文档注释可以帮助其他开发人员更好地理解你的代码。通过提供清晰的注释，可以解释代码的目的、使用方法和重要细节，使代码更易于阅读和维护。
- ：许多开发工具和框架可以根据代码中的文档注释来自动生成文档。例如，JSDoc 是一个常用的JavaScript文档生成工具，它可以解析文档注释并生成API文档。这样其他开发人员就可以轻松地查看代码的接口和用法。
- ：通过文档注释，可以明确说明函数、类、方法和参数的用途、类型和预期行为。这不仅帮助其他开发人员正确使用你的代码，还可以在团队协作中提供一致性和规范。
- ：当你在调试和维护代码时，文档注释可以提供有关代码功能和实现细节的重要信息。这对于理解复杂的功能和排查问题非常有帮助，尤其是当你需要处理他人编写的代码或长时间未接触的代码时。
- ：文档注释可以为开发团队提供一个共享的知识库，使所有人都能理解代码的功能和实现细节。这有助于提高团队成员之间的沟通和协作，并促进代码质量和一致性。
行注释对于编辑器来说是无效的注释,虽然从名字上看上去应该是一个方法，但是编辑器()不知道它是一个函数
当鼠标放到函数上时，编辑器并不知道这个函数的功能是“函数防抖”
当鼠标放到参数上时，编辑器并不知道这个参数是函数
在使用函数成员时，能有效的降低书写错误。因此，你在使用函数里面的一些成员的时候
如：当你在函数内部使用,它没有智能提示，因为它不知道是一个函数
那你稍微不注意把单词写错成，就增加了出错的几率啊。
在开发过程中，有相当一部分程序问题就是由于单词拼写错误导致的。
在函数使用的时候我们能从这个单词的含义知道，它是一个防抖函数，如果我们把这个函数的名称改成，我们不知道他的作用是什么，使用的时候没有任何提示，只知道要传2个参数，至于参数的含义、类型等等都不知道。因此我们最好是写文档注释。
函数
如下我们可以给函数写一个注释:
- 当鼠标放到函数上时，它就会提示这个函数的名字是
- 当我们使用的时候，同样的可以看到它是的函数
由于平时封装的函数日积月累，如果不添加文档注释的话，很多函数都忘记其作用了。
参数标签 @param
参数类型 {}
针对函数每一个参数也可以添加文档注释，其中以关键字(parameter) 开始,格式如下：
如下所示:
- 参数 类型是
- 参数类型是
当我们把鼠标放到这个参数上时，编辑器就知道
是函数。
所以在实现这个函数的时候，当我们使用、这些函数方法的时候都有提示了。
当我们需要调用这个函数时，鼠标放到调用的函数上的时候，编辑器就会告诉我这个参数是一个函数。
参数注释
可以给这个参数呢加上注释，如下示例
现在我们再用鼠标放到参数上看看编辑器会怎么提示我们：
对象属性属性注释
- - 是字符串
- - 是字符串选项,可以是也可以是
- - 是对象
- - 是对象
使用带有对象属性注释的参数
我们看看编辑器会怎么提示我们：
返回值标签 @returns
针对有返回值函数可以添加返回值的注释，其中以关键字开始,格式如下：
注释
这样返回值的类型也确定下来了，我们看看编辑器是怎么提示我们的：
作者标签 @author
可以添加作者有关的注释，其中以关键字开始,格式如下：
我们看看编辑器会怎么提示我们，点击还可以发邮件。
许可证标签 @license
可以添加版权有关的注释，其中以关键字开始,格式如下：
在使用 @license 标签时，开发者应该根据代码的实际许可情况填写适当的许可证信息。这有助于提供清晰的许可证声明，保护代码的知识产权，并促进合规和合理的代码使用。
许可证分类
1. 开源许可证（Open Source Licenses）
这些许可证基于开源原则，允许使用、修改和分发源代码或衍生作品。常见的开源许可证包括许可证、许可证、Apache许可证等。
下面是各种常见许可证之间的差异的详细比较表格：
下面是各列的解释：
- 类型：许可证类型，分类为 “强保护”（对派生作品有限制）和 “弱保护”（提供更大的自由度）。
- 商业使用：许可证是否允许商业使用。
- 分发修改：许可证是否允许分发修改后的代码。
- 源代码发布：许可证是否要求源代码的公开发布。
- 声明更改：许可证是否要求在修改后的代码中声明更改。
- 分发条件：许可证对分发软件的条件要求。
- 专利许可：许可证是否授予使用专利的权利。
- 网络服务使用：许可证是否允许使用者基于该软件提供网络服务。
- 许可证嵌入：许可证是否要求在使用软件的产品中嵌入许可证信息。
请注意，这个表格只提供了对常见许可证之间的主要差异的概述。具体的许可证条款和条件应该参考每个许可证的官方文档和相关说明。选择适当的许可证需要根据项目需求和法律咨询进行综合考虑。另外，这里列出的是一些常见的开源许可证，而还有其他类型的许可证可供选择。
2. 版权声明（Copyright Declaration）
这种分类主要用于声明代码的版权归属，指明作者或组织对代码的所有权。在这种情况下，@license 标签通常包含版权声明和版权所有者的信息。
在这个例子中，我们假设一个名为 “项目一” 的项目，作者为 。他在注释中使用 标签来声明版权信息。下面是每个部分的解释：
- ：指定了项目的版本号。
- ：声明了版权归属于 ，即声明了版权归属于，又指明了版权年份。
- ：说明代码是根据 “项目一许可证” 发布的。
- ：提供了一个链接，指向一个包含详细许可证条款的网页。
3. 私有许可证（Proprietary Licenses）
私有许可证用于保护代码的知识产权，限制未经许可的使用和分发。在这种情况下，@license 标签可能包含具体的许可条款和使用限制，以及联系方式以获取许可。
在这个例子中，我们假设一个名为 “库一” 的库，归属于 。作者明确声明了版权信息，并添加了与私有许可证相关的说明。下面是每个部分的解释：
- ：指定了库的版本号。
- ：声明了版权归属于，并表示保留所有权利。
- ：明确说明这是一款私有软件，未经许可严禁复制或分发软件或其任何部分。
- ：提供了一个联系方式，以便进行许可证相关的咨询。
4. 其他许可证（Other Licenses）
这个分类用于指定其他不属于常见类别的特定许可证。
在这个例子中，我们假设一个名为 “项目一” 的项目，作者为 。他在注释中使用 标签来声明版权信息，并指定了使用的许可证。下面是每个部分的解释：
- ：指定了项目的版本号。
- ：声明了版权归属于 ，并指明了版权年份。
- ：说明代码是根据 发布的。
- : 使用 许可证标识符明确指定了所采用的许可证。
- https://www.apache.org/licenses/LICENSE-2.0：提供了一个链接，指向一个包含详细许可证条款的网页。
示例标签 @example
可以在注释中添加示例，提示如何使用这个函数，其中以关键字开始,格式如下：
我们看看编辑器会怎么提示我们：
定义对象标签 @typedef 和属性标签 @property
在下面的例子中，使用关键字定义了一个名为的类型别名，并使用关键字指定了对象的各个属性及其类型。接下来，函数使用关键字指定了参数的类型为，并使用关键字指定了返回值类型为User`对象。
通过使用关键字，我们可以在文档注释中清晰地指定变量、属性和函数的类型，提高代码可读性和可维护性。
我们看看编辑器会怎么提示我们：
异常标签 @throws
在下面的例子中，函数使用关键字指定了两个参数的类型为，使用关键字指定了返回值类型为，并使用关键字指定了可能抛出的异常类型为。在函数内部，通过判断除数是否为0，如果是则抛出一个错误。
通过使用关键字，我们可以提示其他开发者该函数可能抛出的异常，使其在调用函数时能够更好地处理异常情况。而在调用函数处，可以使用语句捕获并处理异常，避免程序崩溃。
我们看看编辑器会怎么提示我们：
废弃标签 @deprecated
在下面的例子中，通过使用关键字，我们将原来的add函数标记为已废弃，并在注释中说明了该函数已被废弃，建议使用新的函数代替。在代码中，我们首先调用了已废弃的函数来计算两个数字的和，然后使用新的函数来计算多个数字的和。
我们看看编辑器会怎么提示我们：
成员的可见性 @private @protected @public
- _xxxx - 私有成员
- @private - 私有成员
- @protected - 保护成员
- @public- 公共成员
在下面的例子中，我们使用了下划线 来约定将属性标记为私有，以表示该属性应该被视为私有成员。在构造函数中，我们使用注释来说明该属性是私有的。而在方法中，我们并没有使用注释，因为该方法是公共的，可以由外部访问。
在上面的例子中，我们使用了命名约定和注释来模拟 、、 关键字。约定是使用 开头将属性标记为私有，不使用任何特殊约定将属性标记为公共的。
- 属性在 类中是公共的，可以通过对象实例直接访问。
- 属性和 方法在 类中被约定为私有的，但是在 类中仍然可以直接访问。
- 属性和 方法在 类中是公共的，可以通过对象实例直接访问。
- 方法在 类中访问了父类 的 方法。
请注意，这些约定只是一种标准做法，实际上并不能真正实现属性或方法的私有性或保护性。开发者仍然可以绕过约定直接访问被标记为私有的属性。然而，通过使用约定和注释，我们可以向其他开发者传达哪些成员应该被视为私有或保护，以遵循封装的原则。
类 @class 的继承 @extends 与方法的重写 @inheritdoc
在上面的例子中，我们使用了 标签来说明 类继承自 类。然后，在 方法的文档注释中使用了 标签来表示该方法继承并重写了父类的方法。
请注意，这里的 标签只是一种约定，并不是 文档注释的官方标签。不同的文档生成工具可能会对此标签有不同的处理方式。因此，在实际开发中，你需要根据你所使用的文档生成工具的要求来使用适当的标签或约定。
类型 @type 与只读 @readonly
在上述示例中， 标签用于描述 User 类中的 id 属性。这告诉开发人员该属性是只读的，不能在实例创建后进行修改。这样，开发人员在使用该类时就会知道如何正确操作属性。
请注意，JSDoc 标签是一种约定，不同的工具可能会在生成文档时以不同的方式处理标签。但是， 是在 JSDoc 规范中定义的标准标签之一，并且受到广泛支持。因此，它被认为是官方标签。
类 @class 与构造函数 @constructor
在上述示例中， 标签用于描述 类，它表示一个人的类。类的构造函数使用 标签进行注释，以指示这是一个构造函数。
构造函数的文档注释使用 标签描述参数， 参数表示名字， 参数表示年龄。这样，在使用该类时，开发人员可以通过文档了解到构造函数所需的参数和其作用。
通过使用 和 标签，可以为 类提供清晰的文档注释，使其他开发人员能够更好地理解和使用该类。
请注意， 并不对自定义标签提供原生的支持，所以某些工具可能会忽略或不同程度地支持这些标签。但是，通过约定和规范，您可以为您的代码库添加自定义信息，以便更好地记录代码的演化历史。
历史记录@history
在上述示例中，自定义的 标签被用来记录代码的发展历程。每一行记录都包含日期和相应的注释。
使用这种方式，您可以在 注释中记录多个版本、修复或改进的历史信息。这样，其他开发人员在查看文档时可以了解到代码的进展和变化。
日期@history
在上述示例中，我们使用自定义的 标签来记录代码的日期信息。每个标签都包含日期和相应的注释。
使用这种方式，您可以在 JSDoc 注释中记录特定代码片段的创建日期、修改日期或其他相关日期。这样，其他开发人员在查看文档时可以获得更多的上下文信息。
我们可以把这个文档注释，生成一个可读的接口文档
全局安装
你就可以使用这个jsdoc这个命令了
-
- 文件路径
点斜杆表示当前目录的所有文件，下面以生成文档的示例。
首页
debounce 函数
getRandom 函数
request 函数
版权声明：
本文来源网络，所有图片文章版权属于原作者，如有侵权，联系删除。
本文网址：https://www.mushiming.com/mjsbk/5404.html