上面介绍了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

/**
* ................
* @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目录，按照说明运行即可生成；

SmartDoc(YUIDoc) 注释编写的更多相关文章

  1. Python 语法特点：注释/编写规则/命名规范

    1.注释 1)单行注释     # 2) 多行注释   前后三个单引号或双引号   ‘’‘  ...  '''    """  ...""" ...

  2. 让文档和Demo生成更加简单和强大 - SmartDoc 0.1.1 说明

    新特性 smartDoc 0.1.1版正式发布,其中加入了更多方便生成文档的功能,主要特性如下: * 加入@demo配置项,看可以动态抓取html和js的内容作为@example,同时支持扩展@dem ...

  3. jsp_注释

    jsp支持两种注释的语法操作,一种是显示注释(在客户端允许看的见),另一种是隐式注释 显示注释:<!--注释内容--> 隐式注释: 格式一://单行注释 格式二:/*多行注释*/ 格式三: ...

  4. 试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档？

    前言: 一般写完代码之后,还要将各类参数注解写入API文档,方便后续进行对接和测试,这个过程通常都很麻烦,如果有工具可以读取代码注释直接生成API文档的话,那会十分方便. 此前一直都是在使用eolin ...

  5. opencv源码编写规则

    OPENCV作为一种开源的计算机视觉库,我们有必要去了解这个库的一些编码格式及文件结构. 1.文档命名规则 必须将所有功能放入一个或多个.cpp和.hpp文件到OpenCV的相应模块中,或者如果贡献的 ...

  6. IT兄弟连 JavaWeb教程 JSP中的注释

    由于JSP页面由HTML.JSP.Java脚本等组成,所以在其中可以使用多种注释格式 HTML中的注释 HTML语言的注释不会被显示在网页中,但是在浏览器中选择查看网页源代码时,还是能够看到注释的信息 ...

  7. 用python编写一个合格的ftp程序，思路是怎样的？

      经验1.一般在比较正规的类中的构造函数.都会有一个verify_args函数,用于验证传入参数.尤其是对于系统传参.2.并且系统传参,其实后面大概都是一个函数名 例如:python server. ...

  8. Django学习系列5：为视图编写单元测试

    打开lists/tests.py编写 """向浏览器返回真正的HTML响应,添加一个新的测试方法""" from django.test i ...

  9. Python基础部分：4、 python语法之注释

    目录 一.python语法之注释 1.什么是注释 2.如何编写注释 二.PEP8规范 一.python语法之注释 1.什么是注释 注释用来向用户提示或解释某些代码的作用和功能,它可以出现在代码中的任何 ...

随机推荐

  1. atitit.提升软件开发的效率and 质量的那些强大概念and方法总结

    atitit.提升软件开发的效率and 质量的那些强大概念and方法总结 1. 主流编程中三个最糟糕的问题 1 1.1. 从理解问题后到实现的时间很长 1 1.2. 理解和维护代码  2 1.3. 学 ...

  2. atitit.提升开发效率---mda 软件开发方式的革命

    atitit.提升开发效率---mda 软件开发方式的革命 1. 软件开发方式的革命开发工具的抽象层次将再次提升 1 2. 应用框架和其实现相分离 2 3. 目前的问题模型和代码不同步 2 4. MD ...

  3. paip.截取字符串byLastDot方法总结uapi python java php c# 总结

    paip.截取字符串byLastDot方法总结uapi python java php c# 总结 ========uapi   left_byLastDot   right_byLastDot 目前 ...

  4. iOS-图片拉伸技巧

    iOS开发中我们会遇到渐变的背景,内容可变的流式标签,聊天气泡(QQ聊天气泡),由于内容是可变的,宽度和高度同样可变,这样就是导致每次出现的尺寸与之前不一样.如果是需要设置的比较的多,估计美工会烦死, ...

  5. 使用Alcatraz来管理Xcode插件

    Alcatraz 是一个帮你管理 Xcode 插件.模版以及颜色配置的工具.它可以直接集成到 Xcode 的图形界面中,让你感觉就像在使用 Xcode 自带的功能一样. 安装和删除 使用如下的命令行来 ...

  6. iOS-程序发布-32位和64位系统的兼容

    在苹果推出iPhone5S时,64位的应用就走到了眼前.当时就看见苹果官方资料宣布iOS7.x的SDK支持了64位的应用,而且内置的应用都已经是64位. 我记得自己刚刚接触电脑时还有16位的系统,指针 ...

  7. java基础学习总结——java环境变量配置

    前言 学习java的第一步就要搭建java的学习环境,首先是要安装JDK,JDK安装好之后,还需要在电脑上配置"JAVA_HOME”."path”."classpath& ...

  8. Null Object模式

    去除代码中的if(obj==null),或者try/catch语句.维持Code的一致性. Null对象,代表"什么也不做"的一个对象. 使Null对象称为一个匿名内部类确保了该类 ...

  9. windows下clang的安装与使用

    我本意是想在windows下学习下C++11,而结果是我的Visual Studio 2012不完全支持,而我又懒得去安装2013/2015,太大了.公司运维也不允许我去下载- -,然后就想能不能在w ...

  10. 懂DOS终于发挥了一点作用：phoenix bios密码破解

    手上一个笔记本,不知开机密码,但bios是老phoenix的bios,出错后有溢出码,到网上下载了一个unlock6,满怀希望地进行破解,结果一运行,屏幕就没反应.试了几个都不行.最后怀疑是不是输出的 ...