JS註釋&YUIDoc

介紹

做用

• 合做分享：方便他人閱讀，便於分享
• 沉澱總結：容易忘記代碼，總結沉澱

形式

1. // 雙斜槓
2. /**/ 斜槓星號

經常使用標籤

標籤	描述
@module 1	標明當前文件模塊，在這個文件中的全部成員將被默認爲屬於此模塊，除非另外標明
@submodule 1	針對模塊的劃分，處於@module之下
@class	標示一個類或一個函數
@constructor	當使用對象字面量形式定義類時，可以使用此標籤標明構造函數
@callback	標明此方法是一個回調函數
@event	標明一個可觸發的事件函數，一個典型的事件是由對象定義的一組屬性來標示。
@constant	常量標識
@member/@var	記錄一個基本數據類型的成員變量
@method	標記一個方法或函數
@param	標記方法參數及參數類型
@property	標明一個對象屬性
@readonly	只讀
@return	標明返回值、類型及描述
@type	描述代碼變量的類型
@description	若是在註釋開始描述可省略此標籤
@enum	一個類中屬性的類型相同，使用此標籤標明
@example	示例，代碼可自動高了
@exports	標識此對象將會被導出到外部調用
@ignore	忽略此註釋
@link	內聯標籤，建立一個標籤。如'{@link http://github.com Github}'
@name	指定一段代碼的名字，強制JsDoc使用此名稱，而不是代碼裏的名稱
@namespace	指定一個變量命名空間變量
@static	描述一個不需實例便可使用的變量
@summary	對描述信息的短的概述
@throws	描述方法將會出現的錯誤和異常
@todo	描述函數的功能和任務
@tutorial	插入一個指向嚮導教程的連接
@see	標籤容許您引用可能與被記錄的相關的另外一個符號或資源

開發工具

sublime+DocBlockr

/** Tab(回車)自動生成註釋

在註釋中回車自動生成 *

輸入@會自動提示標準註釋的標籤

文檔輸出

YUIDoc
不解析文本，徹底按照註釋標籤進行生成文檔，與代碼分離
NodeJs環境

安裝YUIDoc

npm install –g yuidocjs

使用

1. 在相應的目錄下輸入 yuidoc . ，會在當前目錄生成 out文件，裏面生成註釋文檔
2. 在相應的目錄下輸入 yuidoc . –server <port>，會使用nodejs環境生成對應的網站

更多標籤可參考：

• YUIDoc
• JsDoc

編寫Js註釋

• 以 /* 開頭，/ 結束
• 按照層級格式編寫：@module,[@sumodule],@class,@method,@property等層級格式
• @method，@property，@param等必須在@class下面
• 每一個標籤快裏面只能包含下面一個標籤，描述了當前代碼塊的做用。
• @module 標籤描述一組關聯的類（對於JS 沒有類，YUIDoc只是把有構造方法也歸爲類罷了）。
• @class標籤專門描述類的。在YUI庫中一般是個構造函數。每一個有@class 標籤的註釋塊都應該有一個@static 或者 @constructor的副標籤。
• @method 描述類中的方法。你將會用到 @return 和 @params 副標籤加以說明。
• @property 描述類中的屬性
• @event 描述你自定義的可觸發事件。YUIDoc文檔裏指出