jsduck制作过程

最新推荐文章于 2024-03-31 22:23:33 发布

鹰子

最新推荐文章于 2024-03-31 22:23:33 发布

阅读量1.8k

点赞数

分类专栏： jsduct 文章标签： javascript jsduck 文档

本文链接：https://blog.csdn.net/eagle_88/article/details/50858806

版权

jsduct 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

在网上查了资料后，我最终选择了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里定义
*/