文章转自:hikejun.com/blog/?p=33
需要备上下面三样东西 JSDocTookit http://code.google.com/p/jsdoc-toolkit/
JSDocTookit Ant Task http://code.google.com/p/jsdoc-toolkit-ant-task/
Rhino http://www.mozilla.org/rhino/
再项目的目录下建一个docs目录,编辑Build.xml:
<taskdef name="jsdoctoolkit" classname="uk.co.darrenhurley.ant.tasks.JsDocToolkit"classpath="${jsdoctoolkit.home}jsdoctoolkit-0.4.jar;${rhino.home}js.jar"/>
<jsdoctoolkit jsdochome="${jsdoctoolkit.home}" template="jsdoc" outputdir="./docs" encoding="utf-8">
如果有中文指定输入/输出文件的编码encoding="utf-8" jsdoc的模板文件就是HTML+CSS,所以可以修改成你想要的样子,也可以装上第三方的模板,见http://code.google.com/p/jsdoc-toolkit/wiki/TemplateGallery
关于JSDoc的简单用法: 由于生成的文档页面默认是UTF-8的,所以源文件应该也是UTF-8编码的。
基中一些最常用的标签: /** * @fileoverview 对这个js文件介绍一下 * @author Kejun 维护人的联系方式 * @version 0.0.1 版本 */ 生成之后这段将出现在"File Index"里。
定义类: /** 个人信息类 @class */ var myConfig = { name: "Kejun", title: "Web Developer",
/** 显示我的名字 @function say */ say: function(){ alert("我叫" + this.name); } }; 定义构造器: /** * 一个人物的基类 * @constructor */ function Person(name, title){ this.name = name; this.title = title; }
/** @namespace myApp包括我的一些应用 */ YAHOO.CN.myApp = {}; myConfig, Person, YAHOO.CN.myApp将会出现在“Classes”列表中。
另外常用的对Function的描述: /** * 显示某人的年龄 * @function * @param {string} sName 名字 * @param {number | sring} nAge 年龄 */
属性定义 /** 我的名字 @type string */ 这些将出现在对应的Class/Namespace/Constructor或Global下面。
参考更多JSDoc的所有标签
你还可以使用下面的方法安装:
文章来自:dancewithnet.com/2008/12/30/why-start-yui-doc/
YUI Team实践出了一个高效易协作的前端代码开发流程:代码首先由Ant来组织管理和版本化、接着由JsLint来验证,然后由YUI Doc文档化、最后由YUI Compressor进行压缩发布。上个月初,YUI Team公布了这个新的JavaScript API文档生成工具YUI Doc,它本来专门为YUI提供API级别的文档的,现在它开源为人民服务了。
YUI Doc和JavaDoc、JSDoc和JsDoc Toolkit相似。YUI Doc是由注解驱动(comment-driven )的系统,它通过解析代码中描述结构的注解来生成文档。由于它纯粹的依赖于注解,所以并不像一些模拟系统一样需要有惯用语和代码模式。更详细的介绍可以看YUI Doc的官方文档和YUI blog上的《YUI Doc: A New Tool for Generating JavaScript API Documentation》(由于YUI blog咱们无法访问,比较好的解决方案就是在Google Reader中订阅它的Feed,直接输入 http://yuiblog.com即可。)
YUI Doc是基于Python开发,且依赖几个扩展库,加之其Getting Started写的也比较含糊,所以如何使用这个工具反而成为第一道门槛,尤其对于那些对Python不熟悉的同学来说。所以,下面的重点是介绍如何在Windows上使用YUI Doc:
谢谢小马提供中文注释的解决方案
学会使用工具仅仅是开始了一小步,仔细看看YUI Doc的官方文档吧,利用其来促使我们写出更高效优雅的前端代码并惠及更多的人才是一大步。