最近遇到任务，需要对外提供接口。发现最困难的事是写文档，因为代码经常在修改，每天更新word很困难。然后就发现了文档神器YUI doc，以及神器的剑鞘smartdoc：http://www.cnblogs.com/zhh8077/p/4010991.html。
简单介绍一下使用方法和遇到的坑。
YUI doc可以看成一种标准，主要看这里http://www.cnblogs.com/zhh8077/p/4011769.html或者YUI doc的官方文档。
module写法
|
1 2 3 4 5 6 7 8 9 |
/** * XX模块，包括以下几部分： * * account-账号管理模块</br> * pay-支付管理模块</br> * * * @module XX */ |
class写法
|
1 2 3 4 |
/** * account-账号管理模块 * @class account */ |
method常用写法
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
/** * 登陆 * @method login * @param param {Object} 登陆相关信息</br> * @param param.accountName {string} 用户名 * @param param.password {string} 密码 * @example * // example * account.login({ * accountName: userName, * password:password, * }); */ |
其中 param.xx是二级参数的写法。
event与method一样
常量
|
1 2 3 4 5 6 |
/** * ACCOUNT_STATUS_LOGOUT是一个常量，账号状态为登出，value = "logout" * @property ACCOUNT_STATUS_LOGOUT * @final * @type string */ |
smartdoc的使用就比较简单了，参考其主页文档。
这里主要想说的是 使用过程中遇到的一些坑。
1.生成的method event等等按照字母顺序排列，而不是按照我们文档中的顺序排列。
.YUIDoc生成的API文档目录不按源文件注释顺序
YUIDoc默认将所有的class、method、properties、events等按字母进行排序。
而且这个是在生成文档时进行排序的，所以如果除去按字母进行排序这种默认行为。
就必须修改YUIDoc的工具文件。修改C:\Users\Administrator\AppData\Roaming\npm\node_modules\yuidocjs\lib 下的 builder.js 文件
第1313-1316行，就是这几句罪魁祸首，注释掉后就可以按源文件注释顺序，当然你也可以自己弄其他排序方法。
方法源自：http://www.cnblogs.com/lovesong/p/3341453.html
2.event的example不显示。使用smartdoc生成文档后，其他地方都挺好，但event的example就是显示不出来。chrome上面，直接F12，看document，看到example部分，display：none。method增加了一个active的class，display：block。很简单，看看这个css是在哪里写的。
C:\Users\用户名\AppData\Roaming\npm\node_modules\smartdoc\theme-smart\assets\css
路径下的main.css。改一下其中的example的display就可以了。
修改整个页面的布局也是修改这里。这里就是我们使用的主题，自己可以改，也可以搞一套。