jsdoc-toolkit生成javascriptAPI文档

          

 前言

         对于使用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

评论

1 楼 wangyudong 2017-11-27  

很多API doc生成工具生成doc需要重度依赖代码里加注解的方式，并且不支持自动化测试RESTful API。

之前习惯用一款名字为 WisdomTool REST Client，它能够基于测试过的历史记录自动生成精美的RESTful API文档，完全不用在代码里加注解，支持自动化测试RESTful API，输出精美的测试报告。
轻量级的工具，功能却很精悍哦！

https://github.com/wisdomtool/rest-client

Most of API doc tools do not support automated testing.

Once used a tool called WisdomTool REST Client supports automatically generating exquisite RESTful API documentation based on history testing cases without adding annotations to the code, it also supports automated testing, and outputs exquisite report.

Lightweight tool with very powerful features!

https://github.com/wisdomtool/rest-client