SmartDoc(YUIDoc) 注释编写
上面介绍了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 |
/** |
子模块; 作为@module的扩展,通常使用在很多@class不在一个@module的文件下的扩展 |
@main |
/** |
标示主模块; 主要作为定义目录使用; 例子在@class的同时定义了@module和main那么在生成后json和class JSON将共享同一注释信息 |
@namespace |
/** |
命名空间; 例子中,最终@class的路径会显示为mywidget.Subwidget2 |
@extends | 同上 | 继承标签;作为继承使用 |
@extension @extensionfor |
略 | 扩展标签;同@extends相反,,对类进行扩展 |
@constructor | 同上 |
构造器标签;@class专用; 注意@class如果想使用@example必须要有@constructor |
@static | 静态标示 | |
@final | 常量,不可变标示 | |
@readOnly | 只读 | |
@optional | 可选 | |
@required | 必选 | |
@param |
/** |
参数标签;@method,@constructor的@class和@event可用 @param可以设置子@param但最多为3级;子参数需要使用param.childparam的方式命名; 每个@param可以设置多个类型如:@param {string|function};使用 "|"分割,中间不能有空格 |
@return | 返回值 | |
@chainable | 当返回值为自己的类对象(即this)时使用 | |
@type |
/** |
类型标签;在@porperty和@attribute中使用 |
@deault | 默认值设置 | |
@for |
/** /** |
两种方式,但目标都是@class 1. 指明是哪个@class下的项,@method, @porperty, @attribute, @event使用 2. 设置@class的inner class,@class中使用 |
@private | 私有标识 | |
@protected | 保护标识 | |
@async | 异步方法标识 | |
@uses |
/** |
混入mix便签;可以定义多个 |
@requires |
/** |
模块依赖的标签;标示module使用了那些模块 |
@since |
/** |
标示从哪个版本加入此功能 |
@example |
/** |
代码示例;两种模式: 1. js代码,直接写入js 2. html和js,使用<html></html>和<script></script>包括起来 |
@demo |
/** |
|
@demo |
/** |
smartdoc 0.1.1新增标签; 作为读取html和js文件作为@example使用; 内容配置为文件路径,配合docConfig的demoDir使用; |
@demo (读取jasmine代码片段) |
/** |
文件地址后面的[name]表示jasmine的文件单元测试项,即 it(name,function(){})中的内容; |
@demo (多demo设置和demo title设置) |
/** |
例子中配置了多个@demo,同时在@demo中文件路径的配置加入了{...},表示tab的标题,如果没有设置则取文件名; |
@show | 同上 |
smartdoc 0.1.1新增标签; @show表示直接在页面上显示结果 |
结尾
常用的就这么多,更多信息请查阅 YUIDOC注释编写;
本文例子大多都在 SmartDoc代码 的input目录,按照说明运行即可生成;
SmartDoc(YUIDoc) 注释编写的更多相关文章
- Python 语法特点:注释/编写规则/命名规范
1.注释 1)单行注释 # 2) 多行注释 前后三个单引号或双引号 ‘’‘ ... ''' """ ...""" ...
- 让文档和Demo生成更加简单和强大 - SmartDoc 0.1.1 说明
新特性 smartDoc 0.1.1版正式发布,其中加入了更多方便生成文档的功能,主要特性如下: * 加入@demo配置项,看可以动态抓取html和js的内容作为@example,同时支持扩展@dem ...
- jsp_注释
jsp支持两种注释的语法操作,一种是显示注释(在客户端允许看的见),另一种是隐式注释 显示注释:<!--注释内容--> 隐式注释: 格式一://单行注释 格式二:/*多行注释*/ 格式三: ...
- 试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档?
前言: 一般写完代码之后,还要将各类参数注解写入API文档,方便后续进行对接和测试,这个过程通常都很麻烦,如果有工具可以读取代码注释直接生成API文档的话,那会十分方便. 此前一直都是在使用eolin ...
- opencv源码编写规则
OPENCV作为一种开源的计算机视觉库,我们有必要去了解这个库的一些编码格式及文件结构. 1.文档命名规则 必须将所有功能放入一个或多个.cpp和.hpp文件到OpenCV的相应模块中,或者如果贡献的 ...
- IT兄弟连 JavaWeb教程 JSP中的注释
由于JSP页面由HTML.JSP.Java脚本等组成,所以在其中可以使用多种注释格式 HTML中的注释 HTML语言的注释不会被显示在网页中,但是在浏览器中选择查看网页源代码时,还是能够看到注释的信息 ...
- 用python编写一个合格的ftp程序,思路是怎样的?
经验1.一般在比较正规的类中的构造函数.都会有一个verify_args函数,用于验证传入参数.尤其是对于系统传参.2.并且系统传参,其实后面大概都是一个函数名 例如:python server. ...
- Django学习系列5:为视图编写单元测试
打开lists/tests.py编写 """向浏览器返回真正的HTML响应,添加一个新的测试方法""" from django.test i ...
- Python基础部分:4、 python语法之注释
目录 一.python语法之注释 1.什么是注释 2.如何编写注释 二.PEP8规范 一.python语法之注释 1.什么是注释 注释用来向用户提示或解释某些代码的作用和功能,它可以出现在代码中的任何 ...
随机推荐
- paip.hql的调试故障排查流程总结
paip.hql的调试故障排查流程总结 环境.myeclipse7.0 1 Hql的调试工具myeclipxe默认工具.../Hibernate8IDE 1 故障的排除方法overview 1 Hql ...
- iOS开发-动态和静态FrameWork
开发中我们会使用到第三方的SDK,有的时候也会将整个系统的公用的功能的抽象出来成为FrameWork,我们只需要暴露对外的接口,使用者只需要调用接口,对于内部实现的过程不需要维护,可以以库的形式进行封 ...
- [推荐]PMO学习贴大集合
[推荐]PMO学习贴大集合 http://wenku.baidu.com/view/a9b19bd4240c844769eaeed9.html http://wenku.baidu.com/view/ ...
- 虚拟机评估——如何确定一个CPU核上部署的虚拟机数量?
最近研究虚拟化技术,不可避免遇到一个问题:如何评估物理主机上虚拟主机的容量?下面这篇文章的思路有一定的启发性,转发一下. 如何确定一个CPU核上部署的虚拟机数量? 摘要:本文说明一个CPU核上部署虚拟 ...
- MyBatis 查询
User.java package com.mycom.mybatis_1.bean; import java.io.Serializable; public class User implement ...
- iOS:OC Lib:MagicalRecord
# MagicalRecord 2.1 ## 前言 CoreData是iOS开发中经常使用的数据持久化的技术.但其操作过程稍微繁琐,即使你只是实现简单的存取,不涉及请求优化,也要进行许多配置工作,代码 ...
- nginx+tomcat+java部署总结
昨天部署了一下nginx+tomcat+java出现了很多问题,以下为整理总结. 使用了两种部署方式,一种是源码部署,一种是war部署. java源码部署总结: 环境:nginx+tomcat 部署方 ...
- maven eclipse miss required library解决
我是直接到C:\Users\admin\.m2\repository目录把所有的库包全删除,然后在项目里刷新一下,搞定!
- gem install 出现Errno::ECONNRESET: Connection reset by peer - SSL_connect (https://api.rubygems.org
在安装了rvm来管理多版本的ruby之后,想在不同环境下安装一些gems,结果gem install puma 之后,发现一次又一次失败. gem install 出现Errno::ECONNRESE ...
- 用户管理 之 在Linux系统中,批量添加用户的操作流程
一.阅读此文件您需要掌握的基础知识: <Linux 用户(user)和用户组(group)管理概述><用户(user)和用户组(group)配置文件详解><Linux 用 ...