jsDoc 使用及配置！

jsDoc 说白了就是帮助你生成JS的文档，但有个前提，就是你编写的JS代码中，需要按一定的格式写注释后，这个工具软件才能帮你正确的生成文档！

一、配置使用环境。此软件是 JAVA写的，所以我们要在windows 系统中配置java的环境变量

1、下载jdk（http://java.sun.com/javase/downloads/index.jsp），我下载的版本是：jdk-6u14-windows-i586.exe

2、安装jdk-6u14-windows-i586.exe

3、配置环境变量：右击“我的电脑”-->"高级"-->"环境变量"

1）在系统变量里新建JAVA_HOME变量，变量值为：C:\Program Files\Java\jdk1.6.0_14（根据自己的安装路径填写）

2）新建classpath变量，变量值为：.;%JAVA_HOME%\lib;%JAVA_HOME%\lib\tools.jar

3）在path变量（已存在不用新建）添加变量值：%JAVA_HOME%\bin;%JAVA_HOME%\jre\bin（注意变量值之间用“;”隔开）

4、“开始”-->“运行”-->输入“javac”-->"Enter"，如果能正常打印用法说明配置成功！

补充环境变量的解析:

JAVA_HOME:jdk的安装路径

classpath:java加载类路径，只有类在classpath中java命令才能识别，在路径前加了个"."表示当前路径。

path：系统在任何路径下都可以识别java,javac命令。

 

二、下载 jsdoc_toolkit ，并解压

三、这里我们需要通过命令行进行创建javascript文档。 

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

当然如果感觉通过命令行的方式比较麻烦，我们可以自行创建一个.bat文件
将上面的内容复制到该文件中，执行即可。
下面我来简单解释一下这其中的参数
-a 表示全部的方法
-e 表示对应的文件的编码根式 这里对应的是GB18030 默认的是utf-8
-t 表示生产doc的文档样式模板
这里的test/*.js表示在test目录下的全部javascript文件
执行完毕后将文档结果默认输出到/out/jsdoc目录下。

jsrun.jar app/run.js 可以使用的参数，可以在CMD中输入如下命令进行查看
java -jar jsrun.jar app/run.js --help

 

四、命令名规范

命 令 名 描　　述 
@param  @argument 指定参数名和说明来描述一个函数参数 
@returns         描述函数的返回值 
@author          指示代码的作者 
@deprecated    指示一个函数已经废弃，而且在将来的代码版本中将彻底删除。要避免使用这段代码 
@see               创建一个HTML链接，指向指定类的描述 
@version         指定发布版本 
@requires        创建一个HTML链接，指向这个类所需的指定类 
@throws @exception   描述函数可能抛出的异常的类型 
{@link}           创建一个HTML链接，指向指定的类。这与@see很类似，但{@link}能嵌在注释文本中 
@fileoverview   这是一个特殊的标记。如果在文件的第一个文档块中使用这个标记，则指定该文档块的余下部分将用来提供这个文件的概述 
@class            提供类的有关信息，用在构造函数的文档中 
@constructor   明确一个函数是某个类的构造函数 
@type            指定函数的返回类型 
@extends       指示一个类派生了另一个类。JSDoc通常自己就可以检测出这种信息，不过，在某些情况下则必须使用这个标记 
@private         指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中，除非运行JSDoc时提供了--private命令行选项 
@final             指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量 
@ignore         JSDoc忽略有这个标记的函数

 

五 、注释以/**开头，以*/结束，关键字以@开头

参考网站：http://usejsdoc.org
http://www.36ria.com/5101