注釋說明

1、@class 類標(biāo)識(shí)符。

????????@class?后面可以不跟類名，單獨(dú)使用，但是如果使用@description標(biāo)簽，@class?后面如果跟類名的話必須和類名保持一致，負(fù)責(zé)無法識(shí)別類中的屬性和方法。

2、@callback 回調(diào)函數(shù)標(biāo)識(shí)符。

?????? @callback用來聲明一個(gè)回調(diào)函數(shù)類型以及參數(shù)等信息，可以當(dāng)做函數(shù)的參數(shù)類型使用。

（1）聲明一個(gè)回調(diào)函數(shù)（包括名稱、參數(shù)類型、返回值等詳細(xì)信息）、并且使用

（2） 實(shí)現(xiàn)效果。參數(shù)類型中存在該函數(shù)類型，可以點(diǎn)擊

? ? ? ? ? ? ? ? ? ? ? ? ? ? 點(diǎn)擊函數(shù)類型后跳轉(zhuǎn)到該回調(diào)函數(shù)的具體信息處。

（3）指定屬于某一個(gè)類的回調(diào)函數(shù)。

?????? 語法：@callback namepath~name

?????? 比如我想定義一個(gè)專屬于類AttOper的onOk回調(diào)函數(shù)。

這里cx.AttOper是類AttOper的namepath，

（4）namepath獲取方法如下：

1、存在@namespace標(biāo)簽的話就以@namespace標(biāo)簽里的內(nèi)容為namepath（），如果標(biāo)簽里沒有內(nèi)容，則轉(zhuǎn)到第三部的格式。

2、存在@memberof標(biāo)簽的話就以父元素namepath+類名為namepath。

3、如果既沒有@namespace也沒有@memberof的話，如果有@alias標(biāo)簽，則以@alias標(biāo)簽里的內(nèi)容為namepath；?沒有@alias標(biāo)簽，以@class標(biāo)簽內(nèi)容為namepath；?@class標(biāo)簽也沒有內(nèi)容的話，直接以類名為namepath。

（5）實(shí)現(xiàn)效果（點(diǎn)擊可跳轉(zhuǎn)，且該方法只屬于類AttOper）。

3、@method 方法標(biāo)識(shí)符

（1）描述。

后面不跟內(nèi)容時(shí)默認(rèn)使用下面的方法名，跟內(nèi)容時(shí)則使用其內(nèi)容作為以下方法的方法名

（2）實(shí)現(xiàn)效果

4、@param 參數(shù)標(biāo)識(shí)符。

（1）格式：@param {類型} 參數(shù)名 參數(shù)描述

Param里的參數(shù)類型支持任意類型，也可以吧自定義的函數(shù)作為一個(gè)類型

（2）實(shí)現(xiàn)效果

5、@arguments 指明子類繼承自哪個(gè)父類。

????????????????????????????注意：后面必須跟父類名

實(shí)現(xiàn)效果

6、@alias 別名標(biāo)識(shí)符

可以給類名或者方法名起一個(gè)別名，以實(shí)現(xiàn)在文檔中展示此別名，但是不影響實(shí)際名稱。

如：

實(shí)現(xiàn)效果

7、@alias 另外的用法。

如果想要實(shí)現(xiàn)一個(gè)類中嵌套多個(gè)子類，則可用@alias+@namespace實(shí)現(xiàn)。

（1）首先在主類中加入@namespace聲明和@alias聲明。

（2）然后在子類中添加@alias聲明，注意內(nèi)容格式為（主類@alias內(nèi)容.子類名）如：

（3）實(shí)現(xiàn)效果

（4）點(diǎn)擊后跳轉(zhuǎn)到子類對(duì)象信息頁中。

8、@global 記錄一個(gè)全局對(duì)象

（1）使用@global標(biāo)簽來指定一個(gè)標(biāo)識(shí)應(yīng)記錄為全局。

比如我想把這個(gè)addDeployment方法標(biāo)識(shí)為全局的方法。(注意由于加了global標(biāo)識(shí)后，API文檔里會(huì)把這里的方法名變?yōu)閏lass名+方法名，所以這里需要添加@alias標(biāo)識(shí)來固定方法名)

（2）實(shí)現(xiàn)效果。

9、@example?提供一個(gè)如何使用描述項(xiàng)的例子

（1）使用@example提供一個(gè)如何使用描述項(xiàng)的例子。

跟隨此標(biāo)簽的文字將顯示為高亮代碼。寫法如下：

（2）實(shí)現(xiàn)效果

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

（1）描述。

可以添加自定義的html、htm、markdown(轉(zhuǎn)換Markdown為HTML)、md(轉(zhuǎn)換 Markdown 為 HTML)、.xhtml、xml(作為HTML處理)等格式的文件作為教程放入API文檔中。

（2）加載tutorial需要在jsdoc.conf.json中配置如下（注意指定好路徑）：

（3）文件放入指定文件夾

（4）實(shí)現(xiàn)效果

（5）API中任意位置如何引用教程。

（6）教程引用實(shí)現(xiàn)效果（點(diǎn)擊可跳轉(zhuǎn)到教程頁面）

（7）自定義修改教程名。

教程中的標(biāo)題默認(rèn)是取得文件名，也可以自定義修改，可以在tutorial路徑中新建一個(gè)json文件，文件名隨意，里面進(jìn)行配置如下（注意取得都是文件名作為標(biāo)識(shí)）：

（8）教程名自定義實(shí)現(xiàn)效果

（9）分級(jí)教程實(shí)現(xiàn)效果（父教程里可以跳轉(zhuǎn)到子教程）

11、@mixin和@mixes 記錄一個(gè)mixin（混入）對(duì)象和 此對(duì)象混入了另一個(gè)對(duì)象中的所有成員。

（1）描述。

使用@mixin標(biāo)簽標(biāo)識(shí)該對(duì)象是一個(gè)mixin（混入），旨在表明該對(duì)象的屬性和方法混入到其他對(duì)象。然后，可以將@mixes標(biāo)簽 添加到使用了該 mixin（混入）的對(duì)象上。

@mixes標(biāo)簽指示當(dāng)前對(duì)象混入了OtherObjectPath對(duì)象的所有成員,被混入的對(duì)象就是一個(gè)@mixin。

（2）使用。

?????? 比如我要將Area混入到AttOper中:

（3）實(shí)現(xiàn)效果(點(diǎn)擊可跳轉(zhuǎn))。

12、@extends 指名這個(gè)子類繼承至哪個(gè)父類，后面需要加父類名(別名：@augments).

（1）描述:

?????? @augments?or@extends標(biāo)簽指明標(biāo)識(shí)符繼承自哪個(gè)父類，后面需要加父類名。你可以使用這個(gè)標(biāo)簽來記錄基于類和并基于原型的繼承。如果一個(gè)標(biāo)識(shí)符繼承自多個(gè)父類，并且多個(gè)父類有同名的成員，JSDoc使用來自列出的JSDoc注釋中最后一個(gè)父類的文檔。

（2）使用。

?????? 注意，后面跟的類名以該類中@alias標(biāo)簽中的名字為準(zhǔn)。

（3）實(shí)現(xiàn)效果（點(diǎn)擊可跳轉(zhuǎn)）。

13、@typedef記錄一個(gè)自定義的類型。

（1） 描述。

???? @typedef標(biāo)簽在描述自定義類型時(shí)是很有用的，特別是如果你要反復(fù)引用它們的時(shí)候。尤其是針對(duì)復(fù)雜的數(shù)據(jù)類型的時(shí)候。

（2）使用說明。

?????? 比如我要自定義一個(gè)復(fù)雜的數(shù)據(jù)類型，其包含多個(gè)屬性。

（3）實(shí)現(xiàn)效果（點(diǎn)擊可跳轉(zhuǎn)）。

14、@link 生成一個(gè)鏈接指向定義的namepath或者URL

（1）描述。

?????? {@link}內(nèi)聯(lián)標(biāo)簽創(chuàng)建一個(gè)鏈接到您指定的namepath或URL。當(dāng)您使用{@link}標(biāo)簽，還可以提供幾種不同的格式的鏈接文本。如果你不提供任何鏈接文本，JSDoc使用namepath或URL作為鏈接文字。如果需要鏈接到一個(gè)教程，使用{@tutorial}?內(nèi)聯(lián)標(biāo)簽?代替{@link}標(biāo)簽。

（2）使用。

?????? 注意：@link標(biāo)簽及其文本必須放到花括號(hào){}中，@link標(biāo)簽中的文本可以起別名，格式為：文本內(nèi)容|別名（別名放在文本內(nèi)容后面，中間用|隔開）

（3）實(shí)現(xiàn)效果（點(diǎn)擊可跳轉(zhuǎn)）。

15、@abstract 這個(gè)成員必須在繼承類中實(shí)現(xiàn)（或重寫）。

說明

別名：?@virtual。該成員（一般指父類的方法）必須在繼承的子類中實(shí)現(xiàn)（或重寫）。

16、@access 指定該成員的訪問級(jí)別（私有 private，公共 public，或保護(hù) protected）

說明

????? 該標(biāo)簽指定該成員的訪問級(jí)別（私有 private，公共 public，或保護(hù) protected）。你可以使用與@access標(biāo)簽同義的其他標(biāo)簽：

@access private?等價(jià)于?@private;

@access protected?等價(jià)于?@protected;

@access public?等價(jià)于?@public;

注意: 私有成員（@private）不會(huì)顯示在生成的輸出文檔中。

語法

?????? @access

17、@author 指定項(xiàng)目的作者。

（1）說明

?????? @author標(biāo)簽標(biāo)識(shí)一個(gè)項(xiàng)目的作者。在JSDoc3.2和更高版本中，如果作者的名字后面跟著尖括號(hào)括起來的電子郵件地址， 默認(rèn)模板將電子郵件地址轉(zhuǎn)換為mailto:鏈接。比如：

（2）語法

????? @author []

（3）使用說明

（4）實(shí)現(xiàn)效果

18、@borrows 這個(gè)對(duì)象使用另一個(gè)對(duì)象的某些東西。

（1）說明

@borrows標(biāo)簽允許您將另一個(gè)標(biāo)識(shí)符的描述添加到你的當(dāng)前描述。如果你不止在一個(gè)地方引用同一個(gè)函數(shù)，但是你又不想重復(fù)添加同樣的文檔描述到多個(gè)地方，這個(gè)時(shí)候非常有用。

（2）語法

?????? @borrows as

19、namepath格式說明。

namepath在JSDoc中起著至關(guān)重要的作用，JSDoc

namepath會(huì)提供一個(gè)唯一的標(biāo)識(shí)給任意一個(gè)變量，這使得你在使用inline

tag時(shí)，可以方便的找到任何一個(gè)變量，從而提供一個(gè)指向該變量的鏈接。使用格式如下：

MyConstructor ?????????????? //父元素

MyConstructor#instanceMember ?? //成員變量使用#

MyConstructor.staticMember ??? //靜態(tài)變量使用.

MyConstructor~innerMember ???? //內(nèi)部成員使用~

module: MyConstructor????????????????? // module使用:

20、@constant?記錄一個(gè)對(duì)象作為一個(gè)常量。

（1）描述

????? 別名：@const。標(biāo)簽指明這個(gè)對(duì)象是一個(gè)常量。

（2）語法

?????? @constant[ ]

??????

21、@default 記錄默認(rèn)值。

（1）描述

????? 別名：@defaultvalue。@default標(biāo)簽可以讓你記錄標(biāo)識(shí)的賦值。可以在標(biāo)簽后面跟上他的值，或者當(dāng)值是一個(gè)唯一被分配的簡(jiǎn)單值(可以是：一個(gè)字符串，數(shù)字，布爾值或null)的時(shí)候，你可以讓JSDoc從源代碼中獲取值，自動(dòng)記錄 。

（2）語法

????? @default[]

22、@enum 描述一個(gè)相關(guān)屬性的集合。

（1）描述

????? @enum標(biāo)簽描述一個(gè)靜態(tài)屬性值的全部相同的集合。枚舉類似一個(gè)屬性的集合，除了枚舉自己的描述注釋之外，屬性都記錄在容器內(nèi)部的注釋中。通常這種標(biāo)簽是與@ReadOnly結(jié)合使用，作為一個(gè)枚舉通常表示常量的集合。

（2）語法

????? @enum[]

23、@event 描述一個(gè)事件。

（1）描述

描述一個(gè)事件。@event標(biāo)簽允許您描述一個(gè)可觸發(fā)的事件，一個(gè)典型的事件是由對(duì)象定義的一組屬性來表示。

標(biāo)簽來定義事件的具體類型，您可以使用@fires標(biāo)記，以表明這個(gè)種方法可以觸發(fā)該事件。你還可以使用@listens標(biāo)簽，以指示表明用這個(gè)表示來偵聽該事件。

（2）語法

????? @event#[event:]

24、@fires 描述這個(gè)方法可能會(huì)觸發(fā)哪些事件。

（1）描述

?????? @fires標(biāo)簽標(biāo)明當(dāng)一個(gè)方法被調(diào)用時(shí)將觸發(fā)一個(gè)指定類型的事件，使用@event標(biāo)簽來描述事件的內(nèi)容。

（2）語法

?????? @fires#[event:]

25、@member 記錄一個(gè)成員。

（1）描述

?????? 別名：@var。@member標(biāo)簽記錄成員基本種類（kind），比如"class", "function", 或者 "constant"。一個(gè)成員可以任選地具有一個(gè)類型以及名稱。

（2）語法

?????? @member[] []

26、@memberof 標(biāo)明這個(gè)標(biāo)識(shí)屬于哪個(gè)父級(jí)標(biāo)識(shí)。

（1）描述

????? @memberof標(biāo)簽標(biāo)明成員隸屬于哪一個(gè)父級(jí)標(biāo)識(shí)符。

默認(rèn)情況下，@memberof標(biāo)簽標(biāo)注的標(biāo)識(shí)符是靜態(tài)成員。對(duì)于內(nèi)部成員和實(shí)例成員，你可以使用對(duì)應(yīng)名稱路徑的符號(hào)，或明確標(biāo)注@inner或@instance標(biāo)簽。

“強(qiáng)制的”@memberof標(biāo)簽，@memberof！強(qiáng)制對(duì)象被記錄為屬于特定的父級(jí)標(biāo)識(shí)符，即使它有不同的父級(jí)標(biāo)識(shí)符。

（2）語法

@memberof

@memberof!

在下面的例子中，hammer函數(shù)通常會(huì)被描述為一個(gè)全局性的函數(shù)。事實(shí)上，它就是一個(gè)全局性的函數(shù)，但同事它也是Tools命名空間的一個(gè)成員，而這才是你想描述的。解決方案就是增加一個(gè)@memberof標(biāo)簽。

27、@module 記錄一個(gè)JavaScript 模塊。

（1）描述

@module可以將當(dāng)前文件標(biāo)注為一個(gè)模塊，默認(rèn)情況下文件內(nèi)的所有標(biāo)識(shí)符都隸屬于此模塊，除非文檔另有說明。

鏈接到模塊(比如使用@link或者@see標(biāo)簽)使用"module:moduleName"。例如，可以使用"{@link

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

如果未提供模塊的名稱，那么JSDoc將從模塊的路徑和文件名獲得模塊名稱。

（2）語法

????? @module [[{}] ]

28、@name 記錄一個(gè)對(duì)象的名稱。

（1）描述

@name標(biāo)簽強(qiáng)制JSDoc使用這個(gè)給定的名稱，而忽略實(shí)際代碼里的名稱。這個(gè)標(biāo)簽最好用于"虛擬注釋"，而不是在代碼中隨時(shí)可見的標(biāo)簽，如在運(yùn)行時(shí)期間產(chǎn)生的方法。

當(dāng)您使用@name標(biāo)簽，你必須提供額外的標(biāo)簽，來告訴JSDoc什么樣的標(biāo)識(shí)符將被文檔化;該標(biāo)識(shí)符是否是另一個(gè)標(biāo)識(shí)符的成員;等等。如果不提供這些信息，標(biāo)識(shí)符將不會(huì)被正確文檔化。

警告：通過使用@name標(biāo)簽，你告訴JSDoc忽略實(shí)際代碼，隔離您的文檔注釋。在許多情況下，最好是使用@alias 標(biāo)簽代替，這個(gè)標(biāo)簽只是改變了標(biāo)識(shí)符的名稱，但是保留了標(biāo)識(shí)符的其他信息。

（2）語法

??????????? @name

???????????

29、@namespace 記錄一個(gè)命名空間對(duì)象。

（1）描述

@namespace標(biāo)簽指明對(duì)象是一個(gè)命名空間。你也可以書寫一個(gè)虛擬JSDoc注釋，通過使用代碼來定義命名空間。

如果一個(gè)命名空間是由除對(duì)象字面量以為的標(biāo)識(shí)符定義的，您可以包括一個(gè) type 的表達(dá)式，跟在@namespace標(biāo)簽后面。如果@namespace標(biāo)簽包括一個(gè)type，那么它也必須包含一個(gè)名稱。

您可能需要描述一個(gè)命名空間，其名稱中包含特殊字符，如"#" 或 "!"。在這些情況下，當(dāng)你的描述或鏈接到這個(gè)命名空間時(shí)，你必須將命名空間中特殊符號(hào)部分使用雙引號(hào)括起來。

（2）語法

????? @namespace [{}] ]

30、@override 指明一個(gè)標(biāo)識(shí)符標(biāo)識(shí)重寫父類方法。

（1）描述

????? @override標(biāo)簽指明一個(gè)標(biāo)識(shí)符覆蓋其父類同名的標(biāo)識(shí)符。

默認(rèn)情況下，JSDoc自動(dòng)識(shí)別，覆蓋其父類同名的標(biāo)識(shí)符。

（2）語法

31、@property 記錄一個(gè)對(duì)象的屬性。

（1）描述

@property標(biāo)簽主要用來描述類，命名空間或其它對(duì)象的靜態(tài)屬性列表。

通常JSDoc模板將創(chuàng)造一個(gè)全新的頁面來顯示關(guān)于命名空間嵌套的每一層級(jí)的信息。有時(shí)候，你真的想要在同一張頁面上列出所有屬性，包括嵌套的屬性。

請(qǐng)注意，@property標(biāo)記必須在命名空間或類的文檔注釋塊中使用。該標(biāo)簽適用于靜態(tài)屬性的簡(jiǎn)單集合，它不允許你為每個(gè)屬性提供@examples或類似的復(fù)雜信息，只包含類型，名稱和說明。

（2）語法?????????????????

32、@returns 記錄一個(gè)函數(shù)的返回值。

（1）描述

????? 別名：@return。 標(biāo)簽描述一個(gè)函數(shù)的返回值。

（2）語法

33、