dragonfly环境搭建——jsDuck

作者：zccst

环境安装好了，发现注释也是一个大坑，比如@example，必须要四个缩进。
例如：

    /**
     * 表格
     *
     * @extends Widget
     * @constructor
     * @param {Object} [options] 初始化参数
     * 
     *     @example
     *     {
     *       checkbox:true,     //每列前面是否有复选框
     *       noDataHtml: '没有数据',
     *       columns: [{
     *           label: '名称',  //列头的标题
     *           field: 'name',  //数据字段标示
     *           title: '名称',  //列头的title属性
     *           width: '300px', //列宽，单位：px
     *           align: 'center',//列头标题的对齐方式
     *           sortable: true, //列是否可排序
     *           render: [function(data, row){
     *               return html = '<a href="javascript:void(0);">'+(data + 'bizdev')+'</a>';
     *           },function(data, row){
     *               return data;
     *           }]
     *        }]
     *      }
     */
    function Table(options) {
        Widget.call(this, options);
    }

问了大牛，人家看遍了所有的jsDuck注释，包括每一个注释的含义及注意事项，而且还说这东西很少，一共也没多少。

我想这就是差距。
与牛人的差距：别人看到一个新东西，完完整整看完了，看懂了，不懂的地方通过实践体会；而我不过是走马观花，浅尝辄止，直至用到时向xx求助。求助后，发现就是因为当初看得不够仔细。



二，注释语法
参考URL：https://github.com/senchalabs/jsduck/wiki
Detailed docs for using all the builtin tags:

@abstract
@accessor
@alias
@alternateClassName
@aside
@author
@cfg
@chainable
@class
@constructor
@deprecated
@docauthor
@enum
@event
@evented
@example
@experimental
@extends
@fires (in 5.x beta)
@ftype
@hide
@ignore
@inheritable
@inheritdoc
@localdoc (in 5.x beta)
@markdown
@member
@method
@mixins
@new
@override
@param
@preventable
@private
@property
@protected
@ptype
@readonly
@removed
@requires
@return
@scss mixin
@since
@singleton
@static
@template
@throws
@type
@uses
@var
@xtype
Also for the inline tags:

{@link}
{@img}
{@video}
Various tags use {TypeDefinitions}, the syntax for these is described here:

Type Definitions
















前期准备

    安装 NodeJs
    安装 JSDuck，配置环境变量，熟悉JSDuck注释语法
    安装 RequireJS：npm install -g requirejs，将 r.js 拷贝到 ./tool 下
    安装 JS Beautifier：$ npm install -g js-beautify
    安装 JSHint：$ npm install -g jshint


Generating Ext JS 4 docs  #Ext JS 4是一个项目名称
https://github.com/senchalabs/jsduck/wiki/Usage


官方手册：
https://github.com/senchalabs/jsduck/wiki

New in JSDuck 5
Installation - Help on installing JSDuck.
Usage - Running the JSDuck program.
Introduction to JSDuck - Overview of the main features. Start here.
Categories - List your classes in a systematic manner.
Guides - Write guides and tutorials in addition to API documentation.
Inline examples - Making the live code examples work.
Config file - Pack a load of command line options to a config file.



一、安装jsDuck
分Linux，ISO和Windows版。我安装的Windows版，是下载一个xx.exe文件

双击xx.exe安装报错：
Please specify some input files, otherwise there is nothing I can do

查资料，解决办法：
eg. command ... C:\Users\pavitra\Downloads\jsduck-6.0.0-beta.exe --builtin-classes --output docs


1，简单命令
cd dragonfly->0.3.0                      #进入目标文件夹

[重点，第一个src是要生成注释文档的目标文件夹，第二个--output docs是生成后文件夹保存的位置]
jsduck-6.0.0-beta.exe src --output docs  #成功创建docs


命令含义：
–builtin-classes：构建javascript语言内建类文档，如Array或Object类的使用说明。
–output：文档输出所在目录。
–encoding：编码默认为utf-8，如果js文件中包含了中文字符设置gbk即可。
–welcome:为一个html文件的路径，文件中的内容会被解析出来放到文档的欢迎页显示。
–eg-iframe：配置一个html文件路径，这个html文件用来配置@example范例的预览方式，如需要生成非ExtJs或者sencha touch项目的话通常都需要自定义配置。
–images：如果文档中引入了图片需配置一个图片目录。
–title：自定义文档的标题
–footer：自定义文档脚注
–help：full 显示帮助文档。



那么为什么src里的文件能自动生成基于jsduck的文档？
答：jsduck会在目标文件夹下找所有js文件的注释，以及他们之间的继承关系。
并且按文件夹生成树结构，逐一生成。
对于没有注释的文件或文件夹直接忽略。


jsduck是如何做到的？
答：还在研究中。


2，复合命令
extjs-conf.json

{
    "--": "extjs/src",
    "--warnings": [
        "-no_doc:extjs/src",
        "-no_doc_member:extjs/src",
        "-link:extjs/src",
        "-type_name:extjs/src"
    ],
    "--ignore-html": [
        "locale",
        "debug"
    ],
    "--images": "extjs/docs/images",
    "--builtin-classes": true
}

$ jsduck --config extjs-conf.json --output docs

For additional info on all the different warnings types run jsduck --help=warnings.


如果您觉得本文的内容对您的学习有所帮助，您可以微信：