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文件


jsdoc-toolkit生成javascriptAPI文档_第1张图片
 


 
 

工作模式

通过一段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) {
}

 


 
jsdoc-toolkit生成javascriptAPI文档_第2张图片
 

 
jsdoc-toolkit生成javascriptAPI文档_第3张图片
 

 

jsdoc-toolkit生成javascriptAPI文档_第4张图片
 
 
jsdoc-toolkit生成javascriptAPI文档_第5张图片
 

 

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文档_第6张图片
  • 大小: 28 KB
  • jsdoc-toolkit生成javascriptAPI文档_第7张图片
  • 大小: 2.3 KB
  • jsdoc-toolkit生成javascriptAPI文档_第8张图片
  • 大小: 53 KB
  • jsdoc-toolkit生成javascriptAPI文档_第9张图片
  • 大小: 13.8 KB
  • jsdoc-toolkit生成javascriptAPI文档_第10张图片
  • 大小: 17.9 KB
  • jsdoc-toolkit生成javascriptAPI文档_第11张图片
  • 大小: 49.5 KB
  • jsdoc_toolkit.zip (867.9 KB)
  • 下载次数: 19
  • 查看图片附件

你可能感兴趣的:(jsdoc,jsdoc-toolkit,jsAPI文档)