日期:2014-05-16  浏览次数:20386 次

Arch-05-02-JsDocToolkit注释生成文档-JavaScript

可惜不支持 SC 代码格式,看看源码,想修改一下来支持,结果看到这是调用 mozilla 的 js.jar 包,没办法了,只能找其他的工具了,暂时用 aptana+sc 插件顶住。

?

许多现代编程语言都有自己的集成化文档生成工具,像Java有JavaDoc,.NET有NDoc,PHP有PHPDoc,这些自动化文档工具可以根据代码中的注释自动生成代码文档。
?JsDoc Toolkit就是这样一个自动化文档工具,它是发布在Google code上的一个开源项目,和其他语言的文档工具一样,它可以自动从Javascript代码中提取注释生成格式化文档。
?下载地址
?http://code.google.com/p/jsdoc-toolkit/downloads/list
?运行环境
?JsDoc Toolkit是用Java开发的,运行时需要以下环境:
?1.WindowXP
?java version "1.6.0_03"
?Java(TM) SE Runtime Environment (build 1.6.0_03-b05)
?
2.Mac OS X 10.5
?java version "1.5.0_19"
?Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_19-b02-304)
?其它版本的Java可能导致JsDoc Toolkit运行失败。
?用法
?在运行之前,你需要把当前的工作目录切换到JsDoc Toolkit目录,并确保将java.exe所在目录添加到环境变量中。
java -jar jsrun.jar app\run.js -a -t=templates\jsdoc mycode.js
mycode.js是需要生成文档的js代码,如果mycode.js和JsDoc不在同一目录,请加上文件的绝对或者相对路径。如果项目中有多个js,可以使用通配符*来指定多个js文件(*.js)。-e参数指定文档编码,-t参数指定文档模板位置(可以新建或修改模板文件让输出的代码文件更具特色),生成的文档文件在JsDoc目录下的out目录中。为了使用方便,我写了一个批处理文件,你可以将代码保存为run.bat,放到JsDoc目录下:
::run.bat
@echo off
::js文件名(换成你的js文件名)
set jsname=jquery.js
::js文件路径(换成你的js文件路径)
set jspath=C:\test\
echo start...
java -jar jsrun.jar app\run.js -a -e=utf-8 -t=templates\jsdoc "%jspath%%jsname%.js"
::out\%jsname%\index.html
echo finished.
pause

常用关键字
?author 标识代码作者
class 标识该函数是一个类的构造函数
constant 声明常量
constructor 同class
default 默认值
deprecated 声明已弃用的对象
description 对象描述
event 事件函数
example 例子代码
fileOverview Javascript文件总体描述
ignore 忽略有这个标记的函数
link 与其他JsDoc对象关联
name 显示声明JsDoc不能自动检测的对象
namespace 声明命名空间
param 参数
private 声明私有对象
property 显式声明一个属性
public 声明公开对象
requires 声明所依赖的对象或文件
returns 返回值
see 声明可参考的其它对象
since 声明对象从指定版本开始生效
static 显式声明一个静态对象
throws 声明函数执行过程中可能抛出的异常
type 声明变量类型或者函数返回值类型
version 版本号


详细语法请参阅:JsDoc Toolkit Wiki
?以下是官方提示的示例代码:
/**
* @fileoverview This file is to be used for testing the JSDoc parser
* It is not intended to be an example of good JavaScript OO-programming,
* nor is it intended to fulfill any specific purpose apart from
* demonstrating the functionality of the
* <a href='http://sourceforge.net/projects/jsdoc'>JSDoc</a> parser
*
* @author Gabriel Reid gab_reid@users.sourceforge.net
* @version 0.1
*/
/**
* Construct a new Shape object.
* @class This is the basic Shape class.
* It can be considered an abstract class, even though no such thing
* really existing in JavaScript
* @constructor
* @throws MemoryException if there is no more memory
* @throws GeneralShapeException rarely (if ever)
* @return A new shape
*/
function Shape(){
/**
* This is an example of a function that is not given as a property
* of a prototype, but instead it is assigned within a constructor.
* For inner functions like this to be picked up by the parser, the
* function that acts as a constructor <b>must</b> be denoted with
* the <b>@constructor</b> tag in its comment.
* @type String
*/
this.getClassName = function(){
return "Shape";
}
/**
* This is a private method, just used here as an example
*/
function addReference(){
// Do nothing...
}
}
/**
* Create a new Hexagon instance.
* @extends Shape
* @class Hexagon is a class that is a <i>logical</i> sublcass of
* <a href="Shape.html#">Shape</a> (thanks to the <code>@extends</code> tag), but in
?* reality it is completely unrelated to Shape.
* @param {int} sideLength The length of one side for the new Hexagon
*/
function Hexagon(sideLength) {
}
/**
* This is an unattached (static) function that add