当前位置: 首页 > 工具软件 > JsDoc Toolkit > 使用案例 >

jsdoc-toolkit文档工具使用说明

西门智
2023-12-01

JsDoc Toolkit 是一款辅助工具,你只需要根据约定在 JavaScript 代码中添加相应的注释,它就可以根据这些注释来自动生成API文档。对Java 熟悉的人可能会发现它和 Java 的文档自动化工具 JavaDoc 很像,没错,JsDoc Toolkit 就是基于 JavaDoc 开发的。 项目地址:http://code.google.com/p/jsdoc-toolkit/

由于 JsDoc Toolkit 是用 Java 编写的,所以运行的时候需要 Java 环境。

1、java jdk安装

2、Apache Ant安装和配置

3、JsDoc Toolkit 安装

去 JsDoc Toolkit 的官方主页下载最新的压缩包,解压之后进入 jsdoc-toolkit 目录(即 jsrun.jar 所在的目录),然后运行下面的命令:

java -jar jsrun.jar app/run.js -a -t=templates/jsdoc app/test.js

如果成功的话,你就会看到当前文件夹里多出了一个叫做 out 的文件夹,生成的文档就在里面了!然后你就可以在浏览器中查看了。如果你想了解 JsDoc Toolkit 的高级用法,可以用下面的命令:

java -jar jsrun.jar app/run.js --help

然后就可以看到一些参数说明,这里简单介绍几个: 

-a 或者 –allfunctions :为全部函数生成文档,包括那些没有写注释的。 
-c 或者 –conf :使用配置文件 
-d= 或者 –directory=:指定生成文档的输出目录,默认是 “out” 
-e= 或者 –encoding=:指定编码方式 
-n 或者 –nocode :忽略所有代码,只为有 @name 标签的注释生成文档。 
-o= 或者 –out= : 将日志信息输出到指定文件 
-q 或者 –quiet : 不输出任何信息,包括警告。 
-t= 或者 –template= :指定文档的模板,这个参数必须提供。

4、JsDoc Toolkit标签简介

http://code.google.com/p/jsdoc-toolkit/w/list上可以查看详细的说明。下面列出几个常用的标签。附件是一个示例文件。

@class 类

/** Creates a new Person. 
@class Represents a person. 
*/ 
Person = function() { }

@name 名称

/**
* @name hiliteSearchTerm 
* @function
*/ 
eval("window.hiliteSearchTerm = function(term) {};")

@lends 把匿名对象里的所有成员都作为指定类下的成员输出文档

/** @class */ 
var Person = makeClass( 
/** @lends Person.prototype */
{ 
        initialize: function(name) { 
              this.name = name; 
        }, 
       say: function(message) {
             return this.name + " says: " + message; 
        }
} );

@description 描述信息

/** @description Creates a new Person. 
     @constructor 
*/ 
Person = function() { }

@property 属性

方式1:

/**
* @class 
*/ 
function Person(id) { 
/** 
* The id of the person. 
* @type number
*/ this.id = id;
}

方式2:

/** 
* @class 
* @property {number} id The id of the person. 
*/ 
function Person(id) { 
       this.id = id; 
}

@example 示例

/**
* @example
* var bleeper = makeBleep(3); 
* bleeper.flop(); 
*/


5、JsDoc Toolkit Ant Task使用

JsDoc Toolkit Ant Task 是一个Ant 插件,可以方便的使用Ant来生成文档。

要使用JsDoc Toolkit Ant Task ,需要有Rhino engine。下载Rhino 1.6r7版本,注意最新版本有bug,不能使用。解压后把js.jar拷贝到apache-ant安装文件夹的lib目录下。
下载JsDoc Toolkit Ant Task ,把jsdoc-toolkit-ant-task-1.1.0.jar也拷贝到apache-ant安装文件夹的lib目录下。
只需要按照JsDoc Toolkit Ant Task的说明编写build.xml文件即可。

build.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!--ant的所有内容必须包含在这个里边,name是你给它取的名字,basedir是工作的根目录,.代表当前目录。default代表默认要做的事情-->
<project name="MyProject" default="compress" basedir="D:/Program Files/jsdoc-toolkit/">
  <!-- 设置全局变量 -->
  <property name="source" location="source"/>             <!--源代码所在文件夹,相对于basedir的路径-->
  <property name="document"  location="output/jsdoc"/>    <!--文档输出文件夹-->
  <property name="compressdir" location="Scripts"/>       <!--压缩后js文件输出路径-->
  <property name="template" value="jsdoc"/>               <!--生成文档所用模版名称,jsdoc为默认模版-->
  <property name="iscompress" value="true"/>              <!--是否生成压缩文件-->
  
  <!--生成文档-->
  <target name="buildDocument">
    <echo>正在生成帮助文档...</echo>
    <taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit"/>
    <jsdoctoolkit jsdochome="D:/Program Files/jsdoc-toolkit/" template="${template}" outputdir="${document}" inputdir="${source}">
    </jsdoctoolkit> 
  </target>

  <!--压缩脚本文件-->
  <target name="compress" depends="buildDocument" if="${iscompress}">
    <echo>正在压缩文件...</echo>
    <taskdef name="jsmin" classname="net.matthaynes.jsmin.JSMin_Task"/>
    <jsmin destdir="${compressdir}" force="true">
      <fileset dir="${source}" includes="**/*.js"/>
    </jsmin>
  </target>
</project>



6、JSMin Ant Task

JSMin Ant Task也是一个Ant插件,用来压缩js脚本文件。下载并拷贝jsmin.0.2.4.jar到apache-ant安装文件夹的lib目录下。 使用见build.xml文件。






 类似资料: