版权所有,转载请注明来源http://gogo1217.iteye.com,违者必究!
之前在整理公司框架的时候,曾经为javascript写过一些注释,但没有合适的工具来生成doc文件。后来通过google以及自己试用,发现jsdoc-toolkit和ext-doc2个工具比较有意思。
ext-doc详见:js doc 工具推荐及使用(二):ext-doc
jsdoc-toolkit
官方地址为:http://code.google.com/p/jsdoc-toolkit/
相关注释标签为:http://code.google.com/p/jsdoc-toolkit/w/list
jsdoc-tookit解压后分为4个目录,6个文件。其中templates目录为doc html的模板,如有兴趣和需要可以对模板进行修改和定制。
为了能在ant脚本中使用jsdoc-toolkit,还需要额外的2个包:
jsdoc-toolkit-ant-task.jar ,下载地址为:http://code.google.com/p/jsdoc-toolkit-ant-task/;
js.jar ,下载地址为:https://developer.mozilla.org/en/Rhino_downloads_archive.
1.在eclipse中新建工程如图所示:
其中:
build目录为ant脚本(build-doc.xml),配置文件(build.properties),将ant的变量改为外部应用,以便替换和更改。
doc为jsdoc将来生成doc文件的目录。
jssrc为js源代码文件的存放目录类似于java的源代码文件存放目录为src。
lib为工程中将要使用的额外的jar包,其中build为编译环境所依赖的,有别于运行环境所依赖的包。
在lib中存在着jsdoc-toolkit解压后的文件以及jsdoc-toolkit-ant任务扩展包,以及mozilla旗下的js包,下载后将zip包中的js.jar解压出来即可。
2.配置build.properties如下所示:
##工程根目录 project.dir=.. ###依赖包 lib.dir = ${project.dir}/lib lib.build.jsdoc= ${lib.dir}/build/jsdoc-toolkit-ant-task-1.1.2.jar lib.build.js=${lib.dir}/build/js.jar jsdoc.home=${lib.dir}/build/jsdoc_toolkit-2.4.0/ ##目录 doc.dir=${project.dir}/doc src.dir=${project.dir}/jssrc
3.配置build-doc.xml如下所示:
<?xml version="1.0" encoding="UTF-8"?> <project name="test" default="jsdoc"> <description>test</description> <!--导入配置文件 --> <property file="build.properties" /> <taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit"> <classpath> <pathelement location="${lib.build.jsdoc}" /> <pathelement location="${lib.build.js}" /> </classpath> </taskdef> <tstamp> <format property="build.time" pattern="yyyy-MM-dd-HH-mm" /> </tstamp> <!-- ================================= target: init ================================= --> <target name="init"> <tstamp /> <delete dir="output" /> </target> <!-- ================================= target: doc ================================= --> <target name="jsdoc" depends="init"> <jsdoctoolkit jsdochome="${jsdoc.home}" template="jsdoc" outputdir="${doc.dir}" inputdir="${src.dir}" /> </target> </project>
4.在jssrc下编写demo.js,
仅仅示例 。使用的是jsdoc-toolkit中http://code.google.com/p/jsdoc-toolkit/wiki/CookBook的第一个示例代码。
var MyClass = Class.create( /** @lends MyClass# */ { /** * Description of constructor. * @class Description of class. * @constructs */ initialize : function(arg0, arg1) { //... }, /** A method. */ myFunc : function() { }, /** An instance field. */ myVar : 123 }); // ... and if you want to add class fields ... Object.extend(MyClass, /** @lends MyClass */ { /** A class method. */ classFunc : function() { } });
5.在build-doc.xml右键,在弹出的菜单中选择"Run As"->"Ant Build"。
6.控制台信息
7.doc效果展示
总结:jsdoc-toolkit是一款简单、容易上手的javascript api生成工具。支持是现在流行的多种js oop编写方式,详见http://code.google.com/p/jsdoc-toolkit/wiki/CookBook。
本文中的实例工程打包下载:
http://dl.iteye.com/topics/download/80800fa7-e92a-3ca4-92fa-2d00506db169