JSDoc 是一个根据 JavaScript 文件中注释信息,生成 JavaScript 应用程序或模块的API文档的工具。你可以使用 JSDoc 标记如:命名空间,类,方法,方法参数等。从而使开发者能够轻易地阅读代码,掌握代码定义的类和其属性和方法,从而降低维护成本,和提高开发效率。
它必须以/ **开始,以便由JSDoc解析器识别。其他任何以 /* , /*** 或者超过3个星号的注释,都将被JSDoc解析器忽略。
官网:JSDoc 中文文档
常用注释
@access
指定该成员的访问级别,包含 package
,私有 private
,公共 public
,或保护 protected
@access package
等价于@package
;@access private
等价于@private
;@access protected
等价于@protected
;@access public
等价于@public
@async
表示函数是异步的
@author
标识一个项目的作者
@Callback
提供回调函数(可传递给其他函数)的描述
@class
将函数标记为构造函数,这意味着要使用 new
关键字调用它以返回实例。
@constant
对常量进行描述:@constant [<type> <name>]
@copyright
用来描述一个文件的版权信息:@copyright <some copyright text>
@deprecated
指明一个标识在代码中已经被弃用:@deprecated [<some text>]
@description
记录说明,如果在注释开始的地方添加描述,那么可省略 @description
标签。
@file
提供文件的说明,在文件开头的 JSDoc 注释部分使用:@file <descriptionOfFile>
@function
将一个对象标记为一个函数:@function [<functionName>]
@param
提供函数参数的名称、类型和描述:@param [<type>] <name> [<description>]
@returns
标记记录函数返回的值:@return [{type}] [description]
@version
后面的文本将被用于表示该项的版本:@version <version>