JSDuck安装及使用

Javascript：前端利器 之 JSDuck

目录

背景JSDuck生成的文档效果JSDuck安装步骤

第一步：安装Ruby

第二步：安装Development Kit

第三步：安装rdiscount

第四步：安装jsduckJSDuck

第五步：使用jsduckJSDuck

第6注释

教程备注

背景      返回目录

文档的重要性不言而喻，对于像Javascript这种的动态语言来说就更重要了，目前流行的JDoc工具挺多的，最好的当属JSDuck，可是JSDuck在Windows下的安装非常麻烦，这里就写下来做个备忘。

JSDuck生成的文档效果返回目录

JSDuck安装步骤返回目录

第一步：安装Ruby返回目录

Ruby下载地址：http://rubyinstaller.org/downloads/。

我是64位操作系统，下载的文件如下：

第二步：安装Development Kit返回目录

1、将DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe解压到指定目录，下图是我解压后的位置：

2、使用批处理程序生成config.yml，下面是使用的批处理程序：

1 cd /d D:\Ruby200-x64\dev
2 ruby dk.rb init

3、修改config.yml的内容：

 1 # This configuration file contains the absolute path locations of all
 2 # installed Rubies to be enhanced to work with the DevKit. This config
 3 # file is generated by the 'ruby dk.rb init' step and may be modified
 4 # before running the 'ruby dk.rb install' step. To include any installed
 5 # Rubies that were not automagically discovered, simply add a line below
 6 # the triple hyphens with the absolute path to the Ruby root directory.
 7 #
 8 # Example:
 9 #
10 # ---
11 # - C:/ruby19trunk
12 # - C:/ruby192dev
13 #
14 ---
15 - D:\Ruby200-x64

4、使用批处理执行安装，下面是使用的批处理程序：

1 cd /d D:\Ruby200-x64\dev
2 ruby dk.rb install

第三步：安装rdiscount返回目录

执行如下批处理程序：

1 gem install rdiscount

 

如果失败重新执行

<!--StartFragment -->

gem sources -r https://rubygems.org
      gem sources -a http://rubygems.org 

把https改为http 再执行gem install rdiscount

执行完成后 再改回来

gem sources -r http://rubygems.org

gem sources -a https://rubygems.org

第四步：安装jsduck返回目录

执行如下批处理程序：

1 gem install jsduck

JSDuck教程返回目录

官方永远是最好的学习地方：https://github.com/senchalabs/jsduck/wiki。

备注返回目录

写文档是个好习惯，当然我也相信好代码是最好的文档。

 

第五步：使用jsduck返回目录

Usage

For the simplest test-run just use the --builtin-classes option to write documentation for JavaScript builtin classes like Array, String and Object into docs directory:

$ jsduck --builtin-classes --output docs

To generate docs for Ext JS 4 add path to the corresponding src/ dir:

$ jsduck ext-4.2.1/src --output docs

And to create docs for your own Ext JS project, list the directory with your files in addition to the Ext JS source files (this way the docs of your classes will list all the properties and methods they inherit from Ext JS classes):

$ jsduck ext-4.2.1/src my-project/js --output docs

Unfortunately the above will throw lots of warnings at you, as building the full Ext JS docs requires lots of additional settings. For start you might want to simply ignore all these warnings originating from Ext JS source:

$ jsduck ext-4.2.1/src my-project/js --output docs \
         --warnings=-all:ext-4.2.1/src

But see the Usage guide for more information on building Ext JS 4 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 显示帮助文档。

 

 

第6注释

@author：作者
@class：类
@deprecated：标记此方法属性或者类不赞成使用，在升级过渡的时候需兼容之前的API时特别有用。
@example：给类或者方法添加一个代码范例，jsduck不仅会给代码着色，还能给代码生成一个代码编辑器，编辑代码后可实时预览，使用@example需要四个空格的缩进。
@extends：标记一个类继承自另一个类，生成后会有一个类型继承体系陈列在文档视图的右侧。
@cfg：构造器的配置项，并在其后跟随“{className}”，再跟随参数名。
范例：@cfg {String} fieldName配置项的描述。
@return：与@cfg类似，标记一个函数成员调用过后的返回类型。
范例：@return {Number} 文字描述
@param：与@cfg类似，给一个函数成员标记其所需的参数类型和描述，如果参数类型为多种可以用“/”分割，如需要给参数进行更详细描述还能使用“[param.member]”描述符。
范例：@param {Number/String} fieldName
范例：@param {String[]} fieldName
范例： /**
* @cfg {Object} opt
* @cfg {Number} [opt.age]
* @cfg {Number} [opt.name=0]
*/
@event：标记一个事件，随后通常会跟随@param标签给事件回调函数声明参数的说明。
@inheritdoc：在其后跟随Class#member，常用在子类覆盖父类成员后，子类注释块还需继续使用父类注释的情况下使用。
@private：将成员标记成私有，虽然也有@public但如果不特殊标明即为公有。
@protected：将成员标记成受保护的。
@static:将成员标记成静态的，静态成员也会在文档中进行分类展示。
@img：在文档注释中链接一张图片，让文档变得更具可读性。
@link：在文档注释中标记某个类或类成员的锚点。