SmartDoc(YUIDoc) 註釋編寫

時間 2019-11-07

標籤 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目錄，按照說明運行便可生成；

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。