用jsdoc3自动生成JS API文档

简介

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

预览

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

安装

  1. 安装 node.js
  2. 通过node包管理器(NPM)安装jsdoccmd下运行以下代码
  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实战