? ? ? ? ??
?前言
? ? ? ? ?对于使用JAVA的人来说，查看JavaDoc文档开发非常方便。当我们开发WEB应用的时候，需要javascriptAPI文档开发。在此，我选择了jsDoc-toolkit生成相关文档。
? ? ? ? ?环境：win7,jdk1.7
? ? ? ? ?我在这里就不讲解jdk的安装和配置了，这样的文章太多了。
? ? ? ? 简介
? ? ? ? JsDoc Toolkit 是一款辅助工具，你只需要根据约定在 JavaScript 代码中添加相应的注释，它就可以根据这些注释来自动生成API文档。对Java 熟悉的人可能会发现它和 Java 的文档自动化工具 JavaDoc 很像，没错，JsDoc Toolkit 就是基于 JavaDoc 开发的。
? ? ? ? 下载地址
? ? ? ? ?http://code.google.com/p/jsdoc-toolkit/
? ? ? ? 我这里提供一个版本，提供给上google不方便的人
? ? ? ? 目录结构
app : 存放的是js文件。包括一些实例文件和读取js和模板生成文档的js文件。
conf : 提供默认的配置的文件。
java : 存放的是“rhino”这是一个脚本java写的javascript脚本引擎，用来提供js的运行环境。
templates : 存放生成文档的模板，根据不同的模板可以生成html xml等各种类型文档。
jsrun.jar，jsdebug.jar : 生成的入口调用了rhino框架和js文件
?
?
?
工作模式
通过一段java代码（jsrun.jar）调用rhino框架（该框架提供了一个运行javascript的环境），然后再运行javascript读取生成文档的javascript文件和模板文件生成文档。
注释标签
? ? ? ? 这里的标签是指约定的注释标签，只有写了这些标签， JsDoc Toolkit 才能根据这些标签来生成正确的文档，比如在 @example 之后跟一段小的代码例子。
可用标签列表：http://code.google.com/p/jsdoc-toolkit/wiki/TagReference
使用
? ? ? ? 首先切换到当前目录下，windows执行下面命令
java -jar jsrun.jar app\run.js -a -e=GB18030 -t=templates\jsdoc mycode/*.js
? ? ? ? 如果成功的话，你就会看到当前文件夹里多出了一个叫做 out 的文件夹，生成的文档就在里面了！然后你就可以在浏览器中查看了。
? ? ? ??说明：
“java -jar jsrun.jar app/run.js” ：固定代码，每次运行时都必须含有的。
-a 或者 –allfunctions ：为全部函数生成文档，包括那些没有写注释的。
-c 或者 –conf ：使用配置文件
-d= 或者 –directory=：指定生成文档的输出目录，默认是 “out”
-e= 或者 –encoding=：指定编码方式,这里对应的是GB18030 默认的是utf-8
-n 或者 –nocode ：忽略所有代码，只为有 @name 标签的注释生成文档。
-o= 或者 –out= ： 将日志信息输出到指定文件
-q 或者 –quiet ： 不输出任何信息，包括警告。
-t= 或者 –template= ：指定文档的模板，这个参数必须提供
这里的mycode/*.js表示在mycode目录下的全部javascript文件?
执行完毕后将文档结果默认输出到/out/jsdoc目录下。
查看帮助
? ? ? ? ?java -jar jsrun.jar app/run.js --help
? ? ? ??
/** This is a description of the foo function. */
function foo() {
}
/**
* Represents a book.
* @constructor
@author zeromike
* @param {string} title - 书名.
* @param {string} author - 作者.
*/
function Book(title, author) {
}
?
?
?
?
?
?
?
?
?
?
JS方法参数配置
名称 描 述?
@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
-------------------------------------------------------如果安装nodejs----------------------------------------------------
可以使用grunt-jsdoc插件生成API
https://github.com/krampstudio/grunt-jsdoc
--------------------------------------------------------------------------------------------------------------------------------
参考文章：
http://www.cnblogs.com/rainman/archive/2011/08/14/2137934.html
http://www.cnblogs.com/hxling/archive/2012/11/27/2791067.html
jsdoc-toolkit生成javascriptAPI文档
原文：http://zhangzhaoaaa.iteye.com/blog/2178452