使用YUIdoc

最近遇到任务，需要对外提供接口。发现最困难的事是写文档，因为代码经常在修改，每天更新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写法

/**
 * XX模块，包括以下几部分：
 *
 * account-账号管理模块</br>
 * pay-支付管理模块</br>
 *
 *
 * @module XX
 */

class写法

/**
 * account-账号管理模块
 * @class account
 */

method常用写法

     /**
      * 登陆
      * @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一样

常量

/**
 * 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就可以了。

修改整个页面的布局也是修改这里。这里就是我们使用的主题，自己可以改，也可以搞一套。