YIXUNFE commented 8 years ago

使用 JSDUCK 生成 API 文档

“程序员最讨厌的2件事： ①代码没文档； ② 写文档。” :joy:

如何在工作过程中简单方便的维护好文档，应该是每个程序员都需要考虑的问题。今天我们来认识一下一款常见的文档生成工具 —— JSDUCK。

000

安装与使用

如果你安装了 Ruby，可以使用 gem 安装 JSDUCK。

gem install jsduck

WINDOWS 下还可以直接下载 JSDUCK 的可执行文件，下载无需安装即可使用（八星八箭，只要998）。GITHUB下载地址

命令行执行：

//对单独文件生成文档
jsduck xxx.js --output out

//对目录中文件生成文档
jsduck /src --output out

执行完毕后在当前目录下会生成一个名叫 out 的文件夹，里面存放有 API 文档。浏览器打开 index.html，我们就可以查看文档了。

简单的例子

这里有一份 JS 文件：

"use strict"
;(function () {
  /**
   * Page类，代表一个书页.
   * @constructor
   * @param {string} title - 书本的标题.
   * @param {string} author - 书本的作者.
   */
  function Page (title, anthor) {
    /**
     * 获取书本的标题
     * @return {string|*}
     */     
    this.getTitle=function(){
        return this.title;
    }
  }
  window.Page = Page
}());
/**
 * Book类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book(title, author) {
    this.title=title;
    this.author=author;
}
Book.prototype={
    /**
     * 获取书本的标题
     * @return {string|*}
     */     
    getTitle:function(){
        return this.title;
    },
    /**
     * 设置书本的页数
     * @param pageNum {number} 页数
     */
    setPageNum:function(pageNum){
        this.pageNum=pageNum;
    }
};

生成的文档效果：

为什么选用 JSDUCK

很多同学应该也使用或者听到过 JSDOC 的大名，它们都是为 JS 量身定做的文档生成工具，都按照注释标签生成文档。JSDUCK 与 JSDOC 相比，没有后者对于注释标签使用上的强制性。JSDOC 生成的文档常常是一片惨白，一个字都没有，因为你没有完完全全按照 JSDOC 的注释规范书写注释（所以它很生气啊），所以想要玩转 JSDOC，需要有一定的学习成本。JSDUCK 在使用上则比较简单，目前有很多开源项目在使用 JSDUCK。

注释标签

JSDUCK 的注释标签相对 JSDOC 少一些，其中一些注释标签是我们平时注释常用的，比如 @param，@constructor 等。具体作用可以参考官方文档。

Thanks

luckydrq commented 8 years ago

jsduck不支持es6语法, https://github.com/senchalabs/jsduck/issues/630

yunchuanyang commented 6 years ago

很多标签，我用起来都无效，比如author

YIXUNFE / blog