上面介绍了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. Leetcode 165 Compare Version Numbers

    题意:比较版本号的大小 有点变态,容易犯错 本质是字符串的比较,请注意他的版本号的小数点不知1个,有的会出现01.0.01这样的变态版本号 class Solution { public: int c ...

  2. JS深入了解闭包

    闭包(closure)是Javascript语言的一个难点,也是它的特色,很多高级应用都要依靠闭包实现.   一.变量的作用域 要理解闭包,首先必须理解Javascript特殊的变量作用域. 变量的作 ...

  3. 冒泡算法应用(坐标Y值降序X值升序)

    今天有个客户需求是有一坐标数组,希望按Y值降序X值升序排列,我临时写了个算法.先写个坐标类: class XYZ {     public XYZ() { }     public XYZ(doubl ...

  4. 转:Hide data inside pointers(在指针中隐藏数据)

    该文介绍了如何使用指针中一些未使用的位来隐藏一些数据. When we write C code, pointers are everywhere. We can make a little extr ...

  5. SCN试验之二 checkpoin scn 与数据库scn的关系

    oracle11g 观察数据库scn: SQL> select dbms_flashback.get_system_change_number from dual; GET_SYSTEM_CHA ...

  6. quartzScheduler_Worker-1] but has failed to stop it. This is very likely to create a memory leak解决

    01-Jul-2016 07:24:20.218 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 80 ...

  7. assertThat用法

    一般匹配符1.assertThat( testedNumber, allOf( greaterThan(8), lessThan(16) ) ); 注释: allOf匹配符表明如果接下来的所有条件必须 ...

  8. 新安装的VS的一些设置

    古语云:工欲善其事必先利其器 为了方便我们开发,应该设置好VS的一些配置,安装一些辅助插件 1 设置字体和背景等 设置字体为 console 10大小 背景设为护眼颜色 85 90 205 这三个值 ...

  9. zxing扫码--镭射线

    同步发表于http://avenwu.net/2015/09/15/zxing_view_finder_laser 在很多应用中都有二维码扫描的需求,比如微信,通过扫描电脑二维码,实现用户登录授权: ...

  10. selenium 3.0发布

    记得3年前selenium core team就放出风声selenium3.0将在某个圣诞节发布,然而大家等了3年,就在所有人都不再关注selenium进度的时候,selenium3.0 beta1悄 ...