作为前端工程师,我们工作的成果是什么呢?
没错,是代码。可是,只是代码就可以么?我觉得不是这样的,我们的代码想要让自己以后容易明白,需要清晰的注释;想要让别人理解,更需要完善的文档。因此,代码和文档都是软件工程师工作中非常重要的内容。
可是,为什么我们仍然会看到很多不完善的文档,甚至是错误的文档呢?因为,没人会说,为代码编写文档是件轻松的工作。而当你修改了代码,修复了一个BUG的时候,往往不能及时的将相关的文档更新,同步文档就成为了另一个恼人的工作。
此时,我们就需要一个工具,来自动的生成文档,来方便的同步文档。
幸好工程师一般都有很好的书写注释的习惯,而现在,就有几种工具,可以根据注释的内容来生成文档。
YUIDoc就是其中之一,相对于功能相似的JSDoc,YUIDoc基于PYTHON而不是JAVA,更加轻量,易配置。
下面,就让我们来看一下怎么开始使用YUIDoc来创建文档。
第一步 安装YUI Doc
•下载适用于中文注释的YUI Doc
•安装必要的环境
–Python 2.5
–Setuptools
–Pygments
–SimpleJSON
第二步配置YUI Doc
•配置脚本文件
–YUI Doc 路径
–源JS文件路径
–生成中间文件的路径
–生成文档的路径
–模板路径
–版本号
–YUI版本
第三步运行YUIDoc
•sudo sh example.sh
下面介绍一下它的运行流程
•将原文件拷到中间文件夹并转换编码为utf-8
•生成json数据文件
•生成高亮显示代码页面
•在最终文档文件夹生成文档页面
来简单学习一下使用方法吧…
首先是文件夹结构
module需要放到单独的文件夹中,相同文件夹中的js文件会被认为是同一个module的。
如果不同模块放在相同文件夹,则每个文件要注明@module
生成良好文档的基础是良好的代码结构
•代码要具有良好的oo特性
–模块
–类
–方法
–属性
•正确的注释结构
•标签说明
以下标签每段注释至少都要有一个:
module, class, property, event,method
以上这五个标签都需要在第一行注释写上描述的内容,如下:
/**
* My method description.
* this can span multiple lines.
* @method methodName
*/
除了constructor, public, private, static,其它的标签如果没写名称都会有警告。
•@module 模块名称
将module标签放在组件文件中,它的描述将会出现这个组件的初始页面上。
注:至少需要一个@module标签
/**
*这段注释应该尽量放在文件最前面
*这里是描述,支持多行
*@module 模块名称
*@requires xxx, xxx, xxx 依赖的模块的名称
*/
•@class 类名
/**
*这里是描述,支持多行
*@class 类名称
*@constructor 这里可以不用写东西,表示这个类是可以实例化的
*@static 如果这个类没有constructor,则要加static
*@param 参数名 {参数类型} 参数的说明
*@param 参数名 {参数类型} 第二个参数
*@return {返回类型} 返回值的说明
*@private/protected 不写本行表示为publi
*/
•@method 方法名
/**
*这里是描述,支持多行
*@method 方法名
*@param 参数名 {参数类型} 参数的说明
*@param 参数名 {参数类型} 第二个参数
*@return {返回类型} 返回值的说明
*@private/protected/static
*/
•@event 事件名称
没有return
param 传递给事件监听函数
/**
*这里是描述,支持多行
*@event 事件名称
*@param 参数名 {参数类型} 参数的说明
*/
•@property 属性名
/**
*这里是描述,支持多行
*@property 属性名
*/