jsdoc-toolkit--让JavaScript代码自动生成API文档

介绍

 

JsDoc Toolkit是用javascript编写的开源工具软件。它可以根据JavaScript代码中的约定的标签自动生成格式化模板,多页面HTML(XML,JSON或其他基于文本的格式)的API文档。JsDoc Toolkit来源于Sourceforge上的JSDoc项目，JsDoc Toolkit使用的是JSDoc的语法，实际上，这两个项目的开发者是同一个人：Michael Mathews。

项目地址

 

安装(linux下)

 

JsDoc Toolkit的安装非常简单想，先下载安装包下载地址

安装需要java的支持，JsDoc Toolkit已知的能正常工作的java版本是1.6.0_03与1.5.0_19（如果没有安装java请先到这里下载）

解压JsDoc Toolkit包后，进入jsdoc-toolkit目录

命令以java -jar jsrun.jar app/run.js开头，后面可以附带多个参数，如想查看参数帮助，可以键入--help

java -jar jsrun.jar app/run.js –help

 

下面简单介绍几个常用的参数：其他参数请参考 --help命令

-a or --allfunctions 为所有的函数都生成文档

-d=<目录路径> or --directory=<目录路径> 指定生成文档的路径，默认是当前目录下的out目录

-t=<模板> or --template=<模板路径> 指定要应用的模板路径 ，JsDoc Toolkit是根据模板文件的定义来生成文档的，所以你甚至可以定义自己的模板

 

举例如下，在解压目录下有个templates目录里面自带了jsdoc模板，所以可以用如下命令生成一份文档

java -jar jsrun.jar app/run.js -a -t=templates/jsdoc -d=输出目录路径  /httpd/htdocs/jsdoc  你的JavaScript代码目录

生成结束后在输出目录下会有index.html文件，用浏览器打开即可，页面类此如下，有class索引，文件索引。。。

  

标签约定

 

JsDoc Toolkit是根据源码文件中的约定标签来自动生成文档的，你只有在代码中正确的添加这些标签，JsDoc Toolkit才能生成你想要的文档，下面罗列几个常用的标签：

@author 作者

@constant 常量

@class 类

@param 参数

@example 代码示例

@function 函数

@returns 返回值

@property {属性类型} 属性名

@throws {异常类型} 异常描述

@namespace 命名空间

 

更详细的JsDoc Toolkit的标签说明