SmartDoc(YUIDoc) 註釋編寫

上面介紹了JS文檔和Demo生成工具SmartDoc,本篇開始介紹一下注釋的編寫。SmartDoc使用的是YUIDoc的引擎,因此的註釋規則都同樣,先簡單介紹下YUIDoc的註釋編寫。html

 

編寫註釋是一個很繁重的體力活,不少程序員都嫌麻煩不肯意作此事,可是在編寫的過程,會讓你注意到不少的細節和考慮一些沒有想到的地方,會發現不少的問題和優化點。git

 

爲了比較好的提升效率,從code開始就應該作好規劃,組織文件、模塊、代碼;將單元測試和註釋以及demo綜合考慮,有效的重用;程序員

固然不管怎麼樣都使用smartDoc都會比起單獨的開發文檔和demo要快捷的多。github

推薦sublime下的註釋插件DocBlockr, 鍵入/**後+ tab,能夠自動根據後面的js內容自動生成註釋模板,以下:json

/**
 * [format description]
 * @param  {[type]} tmpl       [description]
 * @param  {[type]} data       [description]
 * @param  {[type]} encodeType [description]
 * @return {[type]}            [description]
 */
function format(tmpl, data, encodeType) {
}

 

註釋標記


 

以 /** 開始, */ 結束,以@指定類型api

//第一種方式
/**
  desc @.... @....
*/ //第二種方式 /**
* desc * @.... * @....
*/

  

  * 第二種方式與第一種不一樣的時,註釋的內容會根據*的位置對齊;兩種方式能夠混用但不建議使用,會使排版很困難。markdown

  * 註釋是能夠空着寫的,不須要非要跟着代碼,yuidoc只會掃描/** .... */ 的內容描述中;異步

  * 描述desc可使用htmlasync

  * 支持markdownide

  * 支持錄入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

/**
* ................
* @method getTargets3
* @demo inherit/getTargets3.js
*/

 

@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目錄,按照說明運行便可生成;

相關文章
相關標籤/搜索