效率

用jsdoc3自动生成JS API文档

简介

  • jsdoc是一款自动产生JS文档的工具。
  • 你得按照它的注释规范来写代码注释，才能够生成合适的文档。
  • 我曾经写过各种风格的混乱注释，用一个个文本来存放管理我的代码库，当我不想再写某段重复难懂的代码的时候，我不得不在我的代码库里游来游去，好头疼啊！！它救了我！！

预览

  • 它可以根据你写的代码自动生成这样的文档出来，看这里。
  • 能够搜索，有详细的注释，保存了完整的代码… 很方便，是不是！
  • 接下来就动手吧！

安装

  1. 安装 node.js
  2. 通过node包管理器(NPM)安装jsdoc，cmd下运行以下代码
  3. 安装完毕
1
npm install jsdoc -g

示例

  • 写类似这样的代码
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    /**
     * @name Uploader
     * @class 异步文件上传组件，支持ajax、flash、iframe三种方案
     * @constructor
     * @extends Base
     * @requires UrlsInput
     * @requires IframeType
     * @requires  AjaxType
     * @param {Object} config 组件配置（下面的参数为配置项，配置会写入属性，详细的配置说明请看属性部分）
     * @param {Button} config.button *，Button按钮的实例
     * @param {Queue} config.queue *，Queue队列的实例
     * @param {String|Array} config.type *，采用的上传方案
     * @param {Object} config.serverConfig *，服务器端配置
     * @param {String} config.urlsInputName *，存储文件路径的隐藏域的name名
     * @param {Boolean} config.isAllowUpload 是否允许上传文件
     * @param {Boolean} config.autoUpload 是否自动上传
     * @example
     * var uploader = new Uploader({button:button,queue:queue,serverConfig:{action:'test.php'}})
     */
    function Uploader(config) { ... }

完整的注释规范：看这里

  • 配置 conf.json
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    {
        "tags": {
            "allowUnknownTags": true
        },
        "source": {
        	"include": ["src"],
            "includePattern": ".+\\.js(doc)?$",
            "excludePattern": "(^|\\/|\\\\)_"
        },
    	"templates": {
    		"cleverLinks": true,
    		"monospaceLinks": true,
    		"default": {
    			"outputSourceFiles" : true
    		},
    		"applicationName": "demo",
    		"openGraph": {},
    		"meta": {}
    	}
    }

完整的conf.json介绍 看这里

  • cmd下输入 jsdoc -c conf.json ，出现的out文件夹就是生成好的文档。

模板

Q: 博主，怎么我生成的文档界面跟你的不一样啊… ( ⊙ o ⊙ )啊！
A: 哦，那是因为我为了吸引你进来特地换了个好看的模板呀。
p.s: 自带模板除了没有搜索，都挺好的。

我直接把jsdoc默认的模板替换了

  1. 图中的模板是 jaguarjs-jsdoc ，下载下来，解压，待用。
  2. 删除清空 C:\%user%\%用户名%\AppData\Roaming\npm\node_modules\jsdoc\templates\default ，然后把 jaguarjs-jsdoc 放入进去即可

参考资料

文中代码来自 使用jsdoc生成组件API文档—jsdoc实战