JSDoc3常用标签使用说明+示例

注释说明

1、@class 类标识符。

        @class 后面可以不跟类名,单独使用,但是如果使用@description标签,@class 后面如果跟类名的话必须和类名保持一致,负责无法识别类中的属性和方法。

2、@callback 回调函数标识符。

       @callback用来声明一个回调函数类型以及参数等信息,可以当做函数的参数类型使用。

(1)声明一个回调函数(包括名称、参数类型、返回值等详细信息)、并且使用

(2) 实现效果。参数类型中存在该函数类型,可以点击

                            点击函数类型后跳转到该回调函数的具体信息处。

(3)指定属于某一个类的回调函数。

       语法:@callback namepath~name

       比如我想定义一个专属于类AttOper的onOk回调函数。


这里cx.AttOper是类AttOper的namepath,

(4)namepath获取方法如下:

1、存在@namespace标签的话就以@namespace标签里的内容为namepath(),如果标签里没有内容,则转到第三部的格式。

2、存在@memberof标签的话就以父元素namepath+类名为namepath。

3、如果既没有@namespace也没有@memberof的话,如果有@alias标签,则以@alias标签里的内容为namepath; 没有@alias标签,以@class标签内容为namepath; @class标签也没有内容的话,直接以类名为namepath。

(5)实现效果(点击可跳转,且该方法只属于类AttOper)。

3、@method 方法标识符

(1)描述。

后面不跟内容时默认使用下面的方法名,跟内容时则使用其内容作为以下方法的方法名

(2)实现效果

4、@param 参数标识符。

(1)格式:@param {类型} 参数名 参数描述

Param里的参数类型支持任意类型,也可以吧自定义的函数作为一个类型

(2)实现效果


5、@arguments 指明子类继承自哪个父类。

                            注意:后面必须跟父类名

实现效果

6、@alias 别名标识符

可以给类名或者方法名起一个别名,以实现在文档中展示此别名,但是不影响实际名称。

如:

实现效果

7、@alias 另外的用法。

如果想要实现一个类中嵌套多个子类,则可用@alias+@namespace实现。

(1)首先在主类中加入@namespace声明和@alias声明。

(2)然后在子类中添加@alias声明,注意内容格式为(主类@alias内容.子类名)如:

(3)实现效果

(4)点击后跳转到子类对象信息页中。

8、@global 记录一个全局对象

(1)使用@global标签来指定一个标识应记录为全局。

比如我想把这个addDeployment方法标识为全局的方法。(注意由于加了global标识后,API文档里会把这里的方法名变为class名+方法名,所以这里需要添加@alias标识来固定方法名)

(2)实现效果。

9、@example 提供一个如何使用描述项的例子

(1)使用@example提供一个如何使用描述项的例子。

跟随此标签的文字将显示为高亮代码。写法如下:

(2)实现效果

10、@Tutorial 添加教程到API文档中。

(1)描述。

可以添加自定义的html、htm、markdown(转换Markdown为HTML)、md(转换 Markdown 为 HTML)、.xhtml、xml(作为HTML处理)等格式的文件作为教程放入API文档中。

(2)加载tutorial需要在jsdoc.conf.json中配置如下(注意指定好路径):

(3)文件放入指定文件夹

(4)实现效果

(5)API中任意位置如何引用教程。

(6)教程引用实现效果(点击可跳转到教程页面)

(7)自定义修改教程名。

教程中的标题默认是取得文件名,也可以自定义修改,可以在tutorial路径中新建一个json文件,文件名随意,里面进行配置如下(注意取得都是文件名作为标识):

(8)教程名自定义实现效果

(9)分级教程实现效果(父教程里可以跳转到子教程)

11、@mixin和@mixes 记录一个mixin(混入)对象和 此对象混入了另一个对象中的所有成员。

(1)描述。

使用@mixin标签标识该对象是一个mixin(混入),旨在表明该对象的属性和方法混入到其他对象。然后,可以将@mixes标签 添加到使用了该 mixin(混入)的对象上。

@mixes标签指示当前对象混入了OtherObjectPath对象的所有成员,被混入的对象就是一个@mixin

(2)使用。

       比如我要将Area混入到AttOper中:

(3)实现效果(点击可跳转)。

12、@extends 指名这个子类继承至哪个父类,后面需要加父类名(别名:@augments).

(1)描述:

       @augments or@extends标签指明标识符继承自哪个父类,后面需要加父类名。你可以使用这个标签来记录基于类和并基于原型的继承。如果一个标识符继承自多个父类,并且多个父类有同名的成员,JSDoc使用来自列出的JSDoc注释中最后一个父类的文档。

(2)使用。

       注意,后面跟的类名以该类中@alias标签中的名字为准。

(3)实现效果(点击可跳转)。

13、@typedef记录一个自定义的类型。

(1) 描述。

     @typedef标签在描述自定义类型时是很有用的,特别是如果你要反复引用它们的时候。尤其是针对复杂的数据类型的时候。

(2)使用说明。

       比如我要自定义一个复杂的数据类型,其包含多个属性。

(3)实现效果(点击可跳转)。

14、@link 生成一个链接指向定义的namepath或者URL

(1)描述。

       {@link}内联标签创建一个链接到您指定的namepath或URL。当您使用{@link}标签,还可以提供几种不同的格式的链接文本。如果你不提供任何链接文本,JSDoc使用namepath或URL作为链接文字。如果需要链接到一个教程,使用{@tutorial} 内联标签 代替{@link}标签。

(2)使用。

       注意:@link标签及其文本必须放到花括号{}中,@link标签中的文本可以起别名,格式为:文本内容|别名(别名放在文本内容后面,中间用|隔开)


(3)实现效果(点击可跳转)。

15、@abstract 这个成员必须在继承类中实现(或重写)。

说明

别名: @virtual。该成员(一般指父类的方法)必须在继承的子类中实现(或重写)。

16、@access 指定该成员的访问级别(私有 private,公共 public,或保护 protected)

说明

      该标签指定该成员的访问级别(私有 private,公共 public,或保护 protected)。你可以使用与@access标签同义的其他标签:

@access private 等价于 @private;

@access protected 等价于 @protected;

@access public 等价于 @public;

注意: 私有成员(@private)不会显示在生成的输出文档中。

语法

       @access

17、@author 指定项目的作者。

(1)说明

       @author标签标识一个项目的作者。在JSDoc3.2和更高版本中,如果作者的名字后面跟着尖括号括起来的电子邮件地址, 默认模板将电子邮件地址转换为mailto:链接。比如

(2)语法

      @author []

(3)使用说明

(4)实现效果

18、@borrows 这个对象使用另一个对象的某些东西。

(1)说明

@borrows标签允许您将另一个标识符的描述添加到你的当前描述。如果你不止在一个地方引用同一个函数,但是你又不想重复添加同样的文档描述到多个地方,这个时候非常有用。

(2)语法

       @borrows as

19、namepath格式说明。

namepath在JSDoc中起着至关重要的作用,JSDoc

namepath会提供一个唯一的标识给任意一个变量,这使得你在使用inline

tag时,可以方便的找到任何一个变量,从而提供一个指向该变量的链接。使用格式如下:

MyConstructor                //父元素

MyConstructor#instanceMember    //成员变量使用#

MyConstructor.staticMember     //静态变量使用.

MyConstructor~innerMember      //内部成员使用~

module: MyConstructor                  // module使用:

20、@constant 记录一个对象作为一个常量。

(1)描述

      别名:@const。标签指明这个对象是一个常量。

(2)语法

       @constant[ ]

      

21、@default 记录默认值。

(1)描述

      别名:@defaultvalue。@default标签可以让你记录标识的赋值。可以在标签后面跟上他的值,或者当值是一个唯一被分配的简单值(可以是:一个字符串,数字,布尔值或null)的时候,你可以让JSDoc从源代码中获取值,自动记录 。

(2)语法

      @default[]

22、@enum 描述一个相关属性的集合。

(1)描述

      @enum标签描述一个静态属性值的全部相同的集合。枚举类似一个属性的集合,除了枚举自己的描述注释之外,属性都记录在容器内部的注释中。通常这种标签是与@ReadOnly结合使用,作为一个枚举通常表示常量的集合。

(2)语法

      @enum[]


23、@event 描述一个事件。

(1)描述

描述一个事件。@event标签允许您描述一个可触发的事件,一个典型的事件是由对象定义的一组属性来表示。

标签来定义事件的具体类型,您可以使用@fires标记,以表明这个种方法可以触发该事件。你还可以使用@listens标签,以指示表明用这个表示来侦听该事件。

(2)语法

      @event#[event:]



24、@fires 描述这个方法可能会触发哪些事件。

(1)描述

       @fires标签标明当一个方法被调用时将触发一个指定类型的事件,使用@event标签来描述事件的内容。

(2)语法

       @fires#[event:]

25、@member 记录一个成员。

(1)描述

       别名:@var。@member标签记录成员基本种类(kind),比如"class", "function", 或者 "constant"。一个成员可以任选地具有一个类型以及名称。

(2)语法

       @member[] []


26、@memberof 标明这个标识属于哪个父级标识。

(1)描述

      @memberof标签标明成员隶属于哪一个父级标识符。

默认情况下,@memberof标签标注的标识符是静态成员。对于内部成员和实例成员,你可以使用对应名称路径的符号,或明确标注@inner@instance标签。

“强制的”@memberof标签,@memberof!强制对象被记录为属于特定的父级标识符,即使它有不同的父级标识符。

(2)语法

@memberof

@memberof!

在下面的例子中,hammer函数通常会被描述为一个全局性的函数。事实上,它就是一个全局性的函数,但同事它也是Tools命名空间的一个成员,而这才是你想描述的。解决方案就是增加一个@memberof标签。

27、@module 记录一个JavaScript 模块。

(1)描述

@module可以将当前文件标注为一个模块,默认情况下文件内的所有标识符都隶属于此模块,除非文档另有说明。

链接到模块(比如使用@link或者@see标签)使用"module:moduleName"。例如,可以使用"{@link

module:foo/bar}"链接到"@module foo/bar"。

如果未提供模块的名称,那么JSDoc将从模块的路径和文件名获得模块名称。

(2)语法

      @module [[{}] ]


28、@name 记录一个对象的名称。

(1)描述

@name标签强制JSDoc使用这个给定的名称,而忽略实际代码里的名称。这个标签最好用于"虚拟注释",而不是在代码中随时可见的标签,如在运行时期间产生的方法。

当您使用@name标签,你必须提供额外的标签,来告诉JSDoc什么样的标识符将被文档化;该标识符是否是另一个标识符的成员;等等。如果不提供这些信息,标识符将不会被正确文档化。

警告:通过使用@name标签,你告诉JSDoc忽略实际代码,隔离您的文档注释。在许多情况下,最好是使用@alias 标签代替,这个标签只是改变了标识符的名称,但是保留了标识符的其他信息。

(2)语法

            @name

           

29、@namespace 记录一个命名空间对象。

(1)描述

@namespace标签指明对象是一个命名空间。你也可以书写一个虚拟JSDoc注释,通过使用代码来定义命名空间。

如果一个命名空间是由除对象字面量以为的标识符定义的,您可以包括一个 type 的表达式,跟在@namespace标签后面。如果@namespace标签包括一个type,那么它也必须包含一个名称。

您可能需要描述一个命名空间,其名称中包含特殊字符,如"#" 或 "!"。在这些情况下,当你的描述或链接到这个命名空间时,你必须将命名空间中特殊符号部分使用双引号括起来。

(2)语法

      @namespace [{}] ]


30、@override 指明一个标识符标识重写父类方法。

(1)描述

      @override标签指明一个标识符覆盖其父类同名的标识符。

默认情况下,JSDoc自动识别,覆盖其父类同名的标识符。


(2)语法


31、@property 记录一个对象的属性。

(1)描述

@property标签主要用来描述类,命名空间或其它对象的静态属性列表。

通常JSDoc模板将创造一个全新的页面来显示关于命名空间嵌套的每一层级的信息。有时候,你真的想要在同一张页面上列出所有属性,包括嵌套的属性。

请注意,@property标记必须在命名空间或类的文档注释块中使用。该标签适用于静态属性的简单集合,它不允许你为每个属性提供@examples或类似的复杂信息,只包含类型,名称和说明。

(2)语法                 


32、@returns 记录一个函数的返回值。

(1)描述

      别名:@return。 标签描述一个函数的返回值。

(2)语法


33、

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 194,524评论 5 460
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 81,869评论 2 371
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 141,813评论 0 320
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 52,210评论 1 263
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 61,085评论 4 355
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 46,117评论 1 272
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 36,533评论 3 381
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 35,219评论 0 253
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 39,487评论 1 290
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 34,582评论 2 309
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 36,362评论 1 326
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 32,218评论 3 312
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 37,589评论 3 299
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 28,899评论 0 17
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 30,176评论 1 250
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 41,503评论 2 341
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 40,707评论 2 335