jsDoc 使用及配置！

浏览数：20 / 时间：2015年06月09日

原文地址：http://www.cnblogs.com/hxling/archive/2012/11/27/2791067.html

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忽略有这个标记的函数