js註釋

 

介紹

做用

合做分享：方便他人閱讀，便於分享

沉澱總結：容易忘記代碼，本身總結沉澱

形式

1.// 雙斜槓

 

2．/**/斜槓星號

 

經常使用標籤

標籤	描述
@module	標明當前文件模塊，在這個文件中的全部成員將被默認爲屬於此模塊，除非另外標明
@submodule	針對模塊的劃分，處於@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	插入一個指向嚮導教程的連接

更多標籤可參考

http://yui.github.io/yuidoc/syntax/index.html

http://usejsdoc.org/

開發工具

sublime+DocBlockr

 

 

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

 

在註釋中回車自動生成 *

 

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

 

文檔輸出

YUIDoc

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

NodeJs環境

https://nodejs.org/download/ 下載node.js

 

安裝YUIDoc

npm install –g yuidocjs

 

使用

在相應的目錄下輸入 yuidoc . ，會在當前目錄生成 out文件，裏面生成註釋文檔

 

在相應的目錄下輸入 yuidoc . –server <port>，會使用nodejs環境生成對應的網站

 

編寫Js註釋

l  以 /** 開頭，*/ 結束

l  按照層級格式編寫

@module,[@sumodule], @class,@method,@property等層級格式

l  @method，@property，@param等必須在@class下面

l  每一個標籤快裏面只能包含下面一個標籤，描述了當前代碼塊的做用。

@module 標籤描述一組關聯的類（對，對，JS 沒有類，YUIDoc只是把有構造方法也歸爲類罷了）。

@class標籤專門描述類的。在YUI庫中一般是個構造函數。每一個有@class 標籤的註釋塊都應該有一個@static 或者 @constructor的副標籤。

@method 描述類中的方法。你將會用到 @return 和 @params 副標籤加以說明。

@property 描述類中的屬性

@event 描述你自定義的可觸發事件。YUIDoc文檔裏指出: