在网上查了资料后,我最终选择了jsduck作为文档生成工具。
一、它生成的网页具有如下特点:
左侧菜单显示类名,右侧显示该类下所有的方法和事件。方法或事件可以带传参(Parameters),使用范例,返回值(Returns)。每个事件右侧标注了该事件所属的类,点击view source可查看该事件定义的原文件位置。网页自带的模糊搜索可方便的查找方法或事件,filter class members可对类下的方法进去过滤,选中event下的事件时,该事件会被展开且高亮显示。。。,所以选择jsduck,用户体验好。
二、接下来是如何用jsduck?我总结如下:
1、下载jsduck.exe文件
windows 二进制版本:https://sourceforge.net/projects/jsduck/files/
2、我放在H盘下,在windows的命令行中输入H:/jsduck-5.3.2.exe --help,显示帮助文档
For example:
# Documentation for builtin JavaScript classes like Array and String
jsduck --output output/dir --builtin-classes
# Documentation for your own JavaScript
jsduck --output output/dir input-file.js some/input/dir
The main options:
-o, --output=PATH Directory to write all this documentation.
--export=full/examples Exports docs in JSON.
--builtin-classes Includes docs for JavaScript builtins.
--seo Enables SEO-friendly print version.
--config=PATH Loads config options from JSON file.
--encoding=NAME Input encoding (defaults to UTF-8).
--exclude=PATH Exclude input file or directory.
Customizing output:
--title=TEXT Custom title text for the documentation.
--footer=TEXT Custom footer text for the documentation.
--head-html=HTML HTML for the <head> section of index.html.
--body-html=HTML HTML for the <body> section of index.html.
--css=CSS Extra CSS rules to include to the page.
--message=HTML (Warning) message to show prominently.
--welcome=PATH File with content for welcome page.
--guides=PATH JSON file describing the guides.
--videos=PATH JSON file describing the videos.
--examples=PATH JSON file describing the examples.
--categories=PATH JSON file defining categories for classes.
--no-source Turns off the output of source files.
--images=PATH Path for images referenced by {@img} tag.
--tests Creates page for testing inline examples.
--import=VERSION:PATH Imports docs generating @since & @new.
--new-since=VERSION Since when to label items with @new tag.
--comments-url=URL Address of comments server.
--comments-domain=STRING A name identifying the subset of comments.
--search-url=URL Address of guides search server.
--search-domain=STRING A name identifying the subset to search fro
m.
Tweaking:
--tags=PATH Path to custom tag implementations.
--ignore-global Turns off the creation of 'global' class.
--external=Foo,Bar,Baz Declares list of external classes.
--[no-]ext4-events Forces Ext4 options param on events.
--examples-base-url=URL Base URL for examples with relative URL-s.
--link=TPL HTML template for replacing {@link}.
--img=TPL HTML template for replacing {@img}.
--eg-iframe=PATH HTML file used to display inline examples.
--ext-namespaces=Ext,Foo Additional Ext JS namespaces to recognize.
--touch-examples-ui Turns on phone/tablet UI for examples.
--ignore-html=TAG1,TAG2 Ignore a particular unclosed HTML tag.
Performance:
-p, --processes=COUNT The number of parallel processes to use.
--[no-]cache Turns parser cache on/off (EXPERIMENTAL).
--cache-dir=PATH Directory where to cache the parsed source.
Debugging:
-v, --verbose Turns on excessive logging.
--warnings=+A,-B,+C Turns warnings selectively on/off.
--warnings-exit-nonzero Exits with non-zero exit code on warnings.
--[no-]color Turn on/off colorized terminal output.
--pretty-json Turns on pretty-printing of JSON.
--template=PATH Dir containing the UI template files.
--template-links Creates symlinks to UI template files.
-d, --debug Same as --template=template --template-link
s.
--extjs-path=PATH Path for main ExtJS JavaScript file.
--local-storage-db=NAME Prefix for LocalStorage database names.
-h, --help[=--some-option] Use --help=--option for help on option.
--version Prints JSDuck version
3、生成文档网页,在命令行中输入H:/jsduck-5.3.2.exe --output H:/lalala H:/js/longhz.tool.js(将longhz.tool.js文件生成的网页文件放在H:/lalala下面),这里只用到了--output配置项,可定义config.json文件存放所有的配置项,如:
{
//文档输出所在目录
"--output":"H:/aicai",
//指定js文件目录或路径,可以是多个,使用数组的方式,如:['extjs/src/app.js','extjs/src/common.js']
"--":["H:/js/longhz.tool.js","H:/js/menu.js"],
//生成文档的title
"--title": "认证后台api",
//生成文档时关闭警告信息
/*"--warnings": [
"-no_doc:extjs/src",
"-no_doc_member:extjs/src",
"-link:extjs/src",
"-type_name:extjs/src"
],*/
//忽略的html标签,通常忽略的是不合法的html标签
/*"--ignore-html": [
"locale",
"debug"
],*/
//配置文件路径
"--images": "H:/images/"
//对于文档标记:{@link Boolean},由于 Ext JS内建了 Boolean 类型,所以JSDuck创建文档时默认采用了Boolean,可以使用此配置来启用或者禁用
//"--builtin-classes": true
}
在命令行中输入H:/jsduck-5.3.2.exe --config H:/config.json,好处是显而易见的,方便修改,备份。
三、实际文档的生成是基于js文件中注释的@tag 标签,注释规范需以“/**” 开头和“*/”结束,标签定义参考https://github.com/senchalabs/jsduck/wiki
如:
/**
* # 描述
* 工具函数。
* @class Global
* @author wzy
*/
/**
* select动态加载
* @event setSelect
* @param {Object} $sel select的jquery对象
* @param {Object} opts 数据对象
* @param {String} initopt select选项默认值
*
* **使用范例**:
*
* @example
* var opts={
* "0":"男",
* "1":"女"
* }
* setSelect($("#selid"),opts,"<option value=''>请选择</option>");
*/
/**
* 自动刷新
* @event autobrush //定义事件
* @param {String} container 容器id,不含# //定义传参
* @param {String} times=5 倒计时时长
* @param {Function} callback 倒计时结束后触发回调函数
*
* **使用范例**: //定义用例
*
* @example
* $.longhz.autobrush({
* "container":"checktable_autobrush_out",
* "times":3,
* "callback":function(){
* statisticTask(taskNames);
* }
* });
* {@img autobrush.png} //定义图片,图片存放目录要在config.json里定义
*/