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目录，按照说明运行便可生成；