文件注釋
文件注釋位於文件的最前面,應包括文件的以下信息:概要說明及版本(必須)項目地址(開源組件必須)版權聲明(必須)開源協議(開源組件必須)版本號(必須)修改時間(必須),以ISO格式表示(可使用Sublime Text的InsertDate插件插入)文件注釋必須全部以英文字符表示,並存在於文件的開發版本與生產版本中。例如:
* jRaiser 2 Javascript Library
* waterfall - v1.0.0 (2013-03-15T14:55:51+0800)
* http://jraiser.org/ | Released under MIT license
*/
* kan.56.com - v1.1 (2013-03-08T15:30:32+0800)
* Copyright 2005-2013 56.com
*/
如果文件內包含了一些開源組件,則必須在文件注釋中進行說明。例如:
* jRaiser 2 Javascript Library
* sizzle - v1.9.1 (2013-03-15T10:07:24+0800)
* http://jraiser.org/ | Released under MIT license
*
* Include sizzle (http://sizzlejs.com/)
*/
普通注釋
普通注釋是為了幫助開發者和閱讀者更好地理解程序,不會出現在API文檔中。其中,單行注釋以“//”開頭;多行注釋以“/*”開頭,以“*/”結束。普通注釋的使用需遵循以下規定。
總是在單行注釋符后留一個空格。例如:
總是在多行注釋的結束符前留一個空格(使星號對齊)。例如:
*/
不要把注釋寫在多行注釋的開始符、結束符所在行。例如:
end */
here is line 1
here is line 2
*/
不要編寫無意義的注釋。例如:
var value = 0;
如果某段代碼有功能未實現,或者有待完善,必須添加“TODO”標記,“TODO”前后應留一個空格。例如:
function setOpacity(node, val) {
node.style.opacity = val;
}
文檔注釋
文檔注釋將會以預定格式出現在API文檔中。它以“/**”開頭,以“*/”結束,其間的每一行均以“*”開頭(均與開始符的第一個“*”對齊),且注釋內容與“*”間留一個空格。例如:
* comment
*/
文檔注釋必須包含一個或多個注釋標簽。
@module。聲明模塊,用法:
/* *
* 模塊說明
* @module 模塊名
*//* *
* Core模塊提供最基礎、最核心的接口
* @module Core
*/
@class。聲明類,用法:
* 類說明
* @class 類名
* @constructor
*/
@class必須搭配@constructor或@static使用,分別標記非靜態類與靜態類。
* 節點集合類
* @class NodeList
* @constructor
* @param {ArrayLike<Element>} nodes 初始化節點
*/
@method。聲明函數或類方法,用法:
* 方法說明
* @method 方法名
* @for 所屬類名
* @param {參數類型} 參數名 參數說明
* @return {返回值類型} 返回值說明
*/
沒有指定@for時,表示此函數為全局或模塊頂層函數。當函數為靜態函數時,必須添加@static;當函數有參數時,必須使用@param;當函數有返回值時,必須使用@return。
* 返回當前集合中指定位置的元素
* @method
* @for NodeList
* @param {Number} [i=0] 位置下標。如果為負數,則從集合的最后一個元素開始倒數
* @return {Element} 指定元素
*/
@param。聲明函數參數,必須與@method搭配使用。
當參數出現以下情況時,使用對應的格式:
參數有默認值:
@property。聲明類屬性,用法:
* 屬性說明
* @property {屬性類型} 屬性名
*/