上面介紹了JS文檔和Demo生成工具SmartDoc，本篇開始介紹一下注釋的編寫。SmartDoc使用的是YUIDoc的引擎，所以的注釋規則都一樣，先簡單介紹下YUIDoc的注釋編寫。
編寫注釋是一個很繁重的體力活，很多程序員都嫌麻煩不願意做此事，但是在編寫的過程，會讓你注意到很多的細節和考慮一些沒有想到的地方，會發現很多的問題和優化點。
為了比較好的提高效率，從code開始就應該做好規划，組織文件、模塊、代碼；將單元測試和注釋以及demo綜合考慮，有效的重用；
當然無論怎么樣都使用smartDoc都會比起單獨的開發文檔和demo要快捷的多。
推薦sublime下的注釋插件DocBlockr, 鍵入/**后+ tab，可以自動根據后面的js內容自動生成注釋模板，如下：
/** * [format description] * @param {[type]} tmpl [description] * @param {[type]} data [description] * @param {[type]} encodeType [description] * @return {[type]} [description] */ function format(tmpl, data, encodeType) { }
注釋標記
以 /** 開始， */ 結束，以@指定類型
//第一種方式 /**
desc @.... @.... */ //第二種方式 /**
* desc * @.... * @.... */
* 第二種方式與第一種不同的時，注釋的內容會根據*的位置對齊；兩種方式可以混用但不建議使用，會使排版很困難。
* 注釋是可以空着寫的，不需要非要跟着代碼，yuidoc只會掃描/** .... */ 的內容描述中;
* 描述desc可以使用html
* 支持markdown
* 支持錄入api鏈接crosslink，格式如：{{#crossLink "module.class/method"}}{{/crossLink}}，例子見@class說明
主標簽
次標簽
| 標簽名 | 注釋 | 說明 |
|---|---|---|
| @submodule |
/** * Provides Y.JSON.parse method to accept JSON strings and return native * JavaScript objects. * * @module json * @submodule json-parse * @for JSON * @static */
|
子模塊； 作為@module的擴展，通常使用在很多@class不在一個@module的文件下的擴展 |
| @main |
/** * The JSON module adds support for serializing JavaScript ... * * @module json * @main json * @class JSON * @static */ |
標示主模塊； 主要作為定義目錄使用； 例子在@class的同時定義了@module和main那么在生成后json和class JSON將共享同一注釋信息 |
| @namespace |
/** * Subclass description. * * @constructor * @namespace mywidget * @class SubWidget2 * @extends Accordion */ |
命名空間； 例子中，最終@class的路徑會顯示為mywidget.Subwidget2 |
| @extends | 同上 | 繼承標簽；作為繼承使用 |
| @extension @extensionfor |
略 | 擴展標簽；同@extends相反，，對類進行擴展 |
| @constructor | 同上 | 構造器標簽；@class專用； 注意@class如果想使用@example必須要有@constructor |
| @static | 靜態標示 | |
| @final | 常量，不可變標示 | |
| @readOnly | 只讀 | |
| @optional | 可選 | |
| @required | 必選 | |
| @param |
/** * 更新操作接口 **[接口方法]** * @method update * @param {object} op 參數； * @param {object} op.filter 過濾器 * @param {object} op.data 更新數據 * @param {object} op.success 成功之后執行的方法 * @param {object} op.error 失敗之后執行的方法 * @return {object} 操作結果 */ |
參數標簽；@method，@constructor的@class和@event可用 @param可以設置子@param但最多為3級；子參數需要使用param.childparam的方式命名； 每個@param可以設置多個類型如：@param {string|function};使用 "|"分割，中間不能有空格
|
| @return | 返回值 | |
| @chainable | 當返回值為自己的類對象（即this）時使用 | |
| @type |
/** * ......... * @property useNativeParse * @type Boolean * @default true * @static */ |
類型標簽；在@porperty和@attribute中使用 |
| @deault | 默認值設置 | |
| @for |
/** * Some method 'bar' * disconnected from * its class 'FarawayClass'... * * @method bar * @for FarawayClass */ /** * Some inner class 'foo'... * * @class foo * @for OuterClass */ |
兩種方式，但目標都是@class 1. 指明是哪個@class下的項，@method, @porperty, @attribute, @event使用 2. 設置@class的inner class，@class中使用 |
| @private | 私有標識 | |
| @protected | 保護標識 | |
| @async | 異步方法標識 | |
| @uses |
/** * @class Panel * @constructor * @extends Widget * @uses WidgetAutohide * @uses WidgetButtons ... */ |
混入mix便簽；可以定義多個 |
| @requires |
/** * @module event-simulate * @requires event */ |
模塊依賴的標簽；標示module使用了那些模塊 |
| @since |
/** * @since 3.4.0 */ |
標示從哪個版本加入此功能 |
| @example |
/** * ui測試類； * @class UI * @constructor * @content {string} type 內容 * @example * <html> * <div id='container'>html render</div> * </html> * * <script> * var ui = new UI("UI測試"); * </script> */
|
代碼示例；兩種模式： 1. js代碼，直接寫入js 2. html和js，使用<html></html>和<script></script>包括起來 |
| @demo |
/** |
|
| @demo |
/** * ................ * @method getTargets3 * @demo inherit/getTargets3.js */
|
smartdoc 0.1.1新增標簽； 作為讀取html和js文件作為@example使用； 內容配置為文件路徑，配合docConfig的demoDir使用； |
| @demo （讀取jasmine代碼片段） |
/** * Deferred對象 * @class Deferred * @constructor * @demo st/deferred.js [resolve] */
|
文件地址后面的[name]表示jasmine的文件單元測試項,即 it(name,function(){})中的內容； |
| @demo （多demo設置和demo title設置） |
/** * ui測試類； * @class UI * @constructor * @content {string} type 內容 * @demo ui.html * @demo ui2.html {ui測試2} * @show true */
|
例子中配置了多個@demo，同時在@demo中文件路徑的配置加入了{...}，表示tab的標題，如果沒有設置則取文件名； |
| @show | 同上 | smartdoc 0.1.1新增標簽； @show表示直接在頁面上顯示結果 |
結尾
常用的就這么多，更多信息請查閱 YUIDOC注釋編寫；
本文例子大多都在 SmartDoc代碼 的input目錄，按照說明運行即可生成；