JGrouseDoc使用(原创）

jGrouseDoc使用

1.      概述描述

jGrouseDoc 可根据 JavaScript 源码生成类似Java Source API的源码文档。可以用这个工具记载需要的所有构造——不仅有函数和变量，还有类文件包，界面，命名空间，包和其它等；

官方网址：http://code.google.com/p/jgrousedoc/

2.      安装设置

下载所需文件

• Latest jGrouseDoc distribution 最新jGrouseDoc
• JRE 5 or newer        提供Java编译环境
• ANT 1.7 or newer,  ANT，基于java和xml的build工具

配置java与ant环境

jGrouseDoc and ANT 都是平台独立的，下载后直接解压缩到相应目录即可使用。JDK可以直接运行安装。但为了使用方便可以设置JRE与Ant命令路径：如下

一、Windows系统

1. 右击【我的电脑】---【属性】-----【高级】---【环境变量】，
2. 选择【新建系统变量】输入“JAVA_HOME”，在“变量值”文本框输入JDK的安装路径，确定；
3. 在“系统变量”选项区域中查看PATH变量，如果不存在，则新建变量 PATH，否则选中该变量，单击“编辑”按钮，在“变量值”文本框的起始位置添加“%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin;”（配置java），然后再添加：”Ant解压缩目录\bin”（配置Ant）

4.    在“系统变量”选项区域中查看CLASSPATH 变量，如果不存在，则新建变量CLASSPATH，否则选中该变量，单击“编辑”按钮，在“变量值”文本框的起始位置添加“.;%JAVA_HOME%\lib\dt.jar;%JAVA_HOME%\lib\tools.jar;”

5. 在DOS命令行窗口分三次输入“JAVAC”、”java”及”ant –v”，输出信息即为配置正确

二、Linux系统

1. 转换到root用户，打开shell输入:”gedit /etc/profile”用文本编辑器打开
2. 在profile文件末尾加入：

export JAVA_HOME=/usr/share/jdk1.6.0_14（jdk1.6.0_14为jdk安装目录）

export PATH=$JAVA_HOME/bin:$PATH

export CLASSPATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar

export PATH=Ant解压目录/bin:$PATH

3. 退出编辑器，shell中输入”source /etc/profile”使用修改的配置文档生效。
4. 测试同windows

配置jGrouseDoc开发环境

进入jGrouseDoc目录，拷贝jgrousedoc.properties和build.xml文件到JS源码文件夹内， build.xml一般不需要修改，而jgrousedoc.properties内要配置文件路径，主要包括以下：

jGrouseHome.default – 指定jGrouseDoc主目录，即解压的jGrouseDoc目录

inputDir.default – 指定包含JS源码文件的输入文件目录

outputDir – 指定输出的文件到指定的目录，每次生成会覆盖之前的文件。

skin – 指定生成API（网页形式的样式）；默认可不添加

theme -指定生成API（网页形式的模式）；默认可不添加

有关一些其它高级配置可以参考：高级配置http://code.google.com/p/jgrousedoc/wiki/AdvancedConfiguration

注意：jgrousedoc.properties中路径无论是Windows还是Linux都要使用正斜杠”\”,如window:”C:\\sample”，Linux:”/home/sample”

3.      生成文档

使用命令行运行jGrouseDoc，原理：使用ant去构建jGrouseDoc提供的build.xml文件，根据xml配置文件生成相应的js API文档

For Linux:

/usr/local/projects/mysuperproject>/path/to/ant/bin/ant

For Windows:

c:\projects\MySuperProject>\path\to\ant\bin\ant

“/path/to/ant是Ant的解压目录；

如果已经按以2小节配置好了Ant的环境变量那，可以直接在命令行中使用ant执行。要构建API文档，可能使用如下命令

ant -f c:\projects\MyJSProject\build.xml （window）或

ant -f home/projects/MyJSProject/build.xml （linux）

其中build.xml为拷贝到JS项目中的xml文档

c:\projects\MySuperProject>\path\to\ant\bin\ant

 

生成实例：

下面介绍windows下如何生成JS API文档的实例，JS源码为JGrouseDoc中提供的sample目录下代码。下载后JGrouseDoc的解压到E盘根目录，结构如下：

路径为：E:\ jGrouseDoc-2.1.1

将目录下的build.xml及jgrousedoc.properties文件拷贝到sample目录下，并打开jgrousedoc.properties，源代码如下：

#set jGrouseHome - location of jGrouseDoc distribution

jGrouseHome.default=.

#set the location of your source files

inputDir.default=sample

#Set mask for input files

fileMask.default=**/*.js

#set output directory

outputDir.default=api

按照提示修改其中目录路径如下：

#set jGrouseHome - location of jGrouseDoc distribution

jGrouseHome.default=E://jGrouseDoc-2.1.1

#set the location of your source files

inputDir.default=E:// jGrouseDoc-2.1.1//sample

#Set mask for input files

fileMask.default=**/*.js

#set output directory

outputDir.default=E:// jGrouseDoc-2.1.1//sample//api

注意使用正斜杠替换反斜杠

运行－输入CMD－输入以下命令：

ant –f E:// jGrouseDoc-2.1.1//sample//build.xml

回车进行构建相应的API文档，完成后在E:// jGrouseDoc-2.1.1//sample//api生成所有文档，默认首索引是一个index.html网页，成功！打开试试吧

关于如何为自己的JS文件添加注释，以便生成相应的API文档可以参考官网教程及实例中代码！下次我再更新，哈哈！！