JavaScript代码API自动化生成

什么是JSDoc?
JSDoc是一个根据javascript文件中注释信息，生成JavaScript应用程序或库、模块的API文档的工具。你可以使用他记录如：命名空间，类，方法，方法参数等。类似JavaDoc和PHPDoc。现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法，并且快速知道如何使用，从而提高开发效率，降低维护成本。
使用JSDoc
JSDoc本质是代码注释，所以使用起来非常方便，但是他有一定的格式和规则，只要了解这些，那么后面的事情，比如生产文档，生成智能提示都可以通过工具来完成。
JSDoc注释
JSDoc注释一般应该放置在方法或函数声明之前，它必须以JSDoc注释一般应该放置在方法或函数声明之前，它必须以/ **开始，以便由JSDoc解析器识别。其他任何以/*，/***或者超过3个星号的注释，都将被JSDoc解析器忽略。在JSDoc 注释有一套标准的注释标签，一般以@开头。当然，不同的ECMAScript规范有着不同的标签，详情可查JSDoc操作手册。

/**

复制代码

* Book类，代表一个书本.

复制代码

* @constructor

复制代码

* @param {string} title - 书本的标题.

复制代码

* @param {string} author - 书本的作者.

复制代码

*/

复制代码

function Book(title, author) {

复制代码

this.title=title;

复制代码

this.author=author;

复制代码

}

复制代码

Book.prototype={

复制代码

/**

复制代码

* 获取书本的标题

复制代码

* @returns {string|*}

复制代码

*/

复制代码

getTitle:function(){

复制代码

return this.title;

复制代码

},

复制代码

/**

复制代码

* 设置书本的页数

复制代码

* @param pageNum {number} 页数

复制代码

*/

复制代码

setPageNum:function(pageNum){

复制代码

this.pageNum=pageNum;

复制代码

}

复制代码

};

复制代码

JSDoc生成文档步骤
1、安装JSDoc和对应的模板，JSDoc有着丰富的模板，而且各种模板还可以选择不同的主题。JSDoc常用的模板主要包括：

tui-jsdoc-template
ink-docstrap
jaguarjs-jsdoc
jsdoc3Template
minami
docdash

/**我只用红色的部分，其它的都没用过*/

复制代码

cnpm install jsdoc -g //或者cnpm ijsdoc -g 我们一般选择全局安装

复制代码

cnpm install ink-docstrap //这个局部安装就可以了

复制代码

2、配置jsdoc.conf.json文件
该配置文件的模板在jsdoc的安装目录和ink-docstrap的安装目录下都有sample，所以我们只需要将两者综合一下就可以了。

{

复制代码

"tags": {

复制代码

"allowUnknownTags": true

复制代码

},

复制代码

"source": {

复制代码

"include": ["../Source/EarthView"], //JavaScript 文件(目录)列表

复制代码

"exclude": ["../Source/EarthView/css", "../Source/EarthView/images"], //在 include 中需要过滤的文件(目录)

复制代码

"includePattern": ".+\\.(js)$" //正则过滤符合规则的文件

复制代码

},

复制代码

"plugins": ["plugins/markdown"], //使用markdown 插件

复制代码

"markdown": {

复制代码

//tags: ["file"], //增加额外需要解析的标签

复制代码

"excludeTags": ["author"], //排除不用解析的标签

复制代码

"parser": "gfm", //gfm

复制代码

"hardwrap": true //允许多行

复制代码

},

复制代码

"templates": { //模板配置，包含了 DocStrap 的配置参数

复制代码

"openGraph": {

复制代码

"title": "",

复制代码

"type": "website",

复制代码

"image": "images/logo.png",

复制代码

"site_name": "",

复制代码

"url": ""

复制代码

},

复制代码

"logoFile": "images/logo.png", //logo 文件路径

复制代码

"cleverLinks": false,

复制代码

"monospaceLinks": false,

复制代码

"dateFormat": "yyyy-mm-dd", //当需要打印日期时使用的格式

复制代码

"outputSourceFiles": false, //是否输出文件源码

复制代码

"outputSourcePath": false, //是否输出源码路径

复制代码

"applicationName": "EarthView参考手册",

复制代码

"systemName": "EarthView API 参考手册", //系统名称

复制代码

"footer": "", //页脚内容

复制代码

"copyright": "engineerhe@foxmail.com", //页脚版权信息

复制代码

"navType": "vertical", //vertical 或 inline

复制代码

//docstrap 模板主题。可取值: cosmo, cyborg, flatly, journal, lumen, paper,

复制代码

//readable, sandstone, simplex, slate, spacelab, superhero, united, yeti

复制代码

"theme": "readable",

复制代码

"linenums": true, //是否显示行号

复制代码

"collapseSymbols": false, //是否折叠太长的内容

复制代码

"inverseNav": true, //导航是否使用 bootstrap 的 inverse header

复制代码

"protocol": "html://", //生成文档使用的阅读协议

复制代码

"methodHeadingReturns": true //method 方法标题上是否包含返回类型

复制代码

},

复制代码

//命令行执行参数配置。在这里配置了后

复制代码

//命令行只需要执行: jsdoc -c jsdoc-conf.json 即可

复制代码

"opts": {

复制代码

"template":"../node_modules/jaguarjs-jsdoc",

复制代码

//"template": "templates/default", //使用 JSDoc 默认模板

复制代码

//"template": "../node_modules/ink-docstrap/template", //使用 docstrap 模板

复制代码

"destination": "./help", //输出目录。等同于 -d ./out/

复制代码

"recurse": true, //是否递归查找。-r

复制代码

"debug": true, //启用调试模式。--debug

复制代码

"readme": "../README.md" //要写到文档首页的 readme 文档。-R README.md

复制代码

}

复制代码

}

复制代码

[code][/code]3、执行命令 jsdoc -c .\jsdoc.conf.json即可生成文档