Ant+JSDocTookit生成Javascript文档

文章转自: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

jsdoctoolkit ant task的详细属性

关于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:

  1. 下载Python2.5.2安装之。 虽然Python3.0和Python2.6都已经出来很久了,但之所以依旧选择Python2.5.2,是因为后面要用到的安装Python扩展库的工具setuptools在Windows下的最新版本对应的是Python2.5。我不知道它是否支持2.5以上,有兴趣的可以试试。
  2. 下载setuptools-0.6c9.win32-py2.5.exe并安装之,setuptools会自动安装到Python所在安装目录的Scripts目录下。 setuptools为Python提供了简单的包管理和发行功能。后面的扩展库的安装就是利用它的easy_install,非常方便。有兴趣的可以看看《可爱的 Python: 使用 setuptools 孵化 Python egg》
  3. 为了使用方便需要配置一下“环境变量”,即在“我的电脑 》右键 》属性 》高级 》环境变量 》系统变量 》 选中Path 》 编辑”,在弹出框中加入: ;D:\Program Files\python;D:\Program Files\python\Scripts 然后应用即可。前面的两个路径分别是我的Python和setuptools的安装路径,你需要修改成你自己的。
  4. 开始 》运行 》(Win + R)输入“cmd”,输入: python -c "import pkg_resources" 没有任何输出,即表示setuptools安装成功。接着依次输入运行: easy_install Pygments easy_install simplejson easy_install Cheetah setuptools会自动寻找并下载PygmentsSimpleJSONCheetah这三个扩展库,并安装它。
  5. 下载最新版本YUI Doc,并解压在某个目录下。复制其bin目录下的example.bat文件,重命名为test.bat,然后用记事本或其他编辑器打开并配置它: SET yuidoc_home="D:\yui\yuidoc" REM YUI Doc的路径 SET parser_in="D:\yui\src" REM 要生成文档的JS文件路径,比如为了测试就我临时建一个,里面就放着YUI 的 dom.js SET parser_out="D:\yui\src\parser" REM YUI Doc会把解析的JS文件提取出来所要存放的位置 SET generator_out="D:\yui\src\generator" REM 生成文档存放的位置 保存并运行test.bat后,就会发现D:\yui\src中多了parser和generator两个目录,而generator中正是你要的文档。
支持中文注释的解决方案
  1. 下载最新版本YUI Doc,解决方案在yuidoc-27中验证通过
  2. 把所有.js文件都转成不带BOM的UTF-8编码
  3. 修改文件/bin/yuidoc_highlight.py: from pygments.formatters import HtmlFormatter #新增下行 import codecs ... #f=open(os.path.join(path, file)) #fileStr=StringIO(f.read()).getvalue() #f.close() fileStr = codecs.open( os.path.join(path, file), "r", "utf-8" ).read() log.info("highlighting " + file) #highlighted = highlightString(fileStr) highlighted = highlightString(unicode(fileStr))
  4. 在Python的\Lib\site-packages\下增加一个名为sitecustomize.py的文件,其内容为: import sys sys.setdefaultencoding('utf-8')

谢谢小马提供中文注释的解决方案

学会使用工具仅仅是开始了一小步,仔细看看YUI Doc的官方文档吧,利用其来促使我们写出更高效优雅的前端代码并惠及更多的人才是一大步。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏开发 & 算法杂谈

基于Lockset的数据竞争检测方法汇总(二)

前一篇文章提到的是使用Lockset最经典的方法,但是存在很多误报,针对这些误报产生的原因,有很多分析并改进了原始的Lockset方法,今天主要和大家谈的就是有...

17870
来自专栏安恒信息

近期APT攻击事件频发—安恒信息再次成功检测到APT攻击样本

>>>> 前言 乌克兰电力系统受到APT攻击事件,给国内外企业和用户都敲响了警钟,与此同时,安恒信息在国内也监控到了多次APT攻击。近期,安恒信息APT威胁分析...

36850
来自专栏我是攻城师

Solr竞价排名之ExternalFileField使用

31590
来自专栏游戏杂谈

php正则表达式的分组捕获

经过测试,发现php正则表达式获取分组捕获是从$0开始,而平时工作中JavaScript中的正则是$1..$9

16530
来自专栏大数据钻研

一个基于Java的开源URL嗅探器

这是一个可以检测并规范化文本中的URL地址的Java库。 ? 今天,我们很高兴做一个分享,因为我所在的 Linkedin 公司 开源了我们做的一个ULR探测工具...

423110
来自专栏解决发现

CPU占用率100%的解决方法

图:优化前(我的电脑是四核cpu,所以单线程无限无阻塞循环占用率不会达到100%)

69400
来自专栏游戏杂谈

url空格转码的问题

最开始我使用的是chrome,发现有脚本报错了,以为是服务器维护了,但再一想,不对啊,刚刚明明是好的,再返回首页,正常。再输入搜索信息,又遇到了这个界面。然后我...

16960
来自专栏数据派THU

独家 | 手把手教你用Python进行Web抓取(附代码)

作为一名数据科学家,我在工作中所做的第一件事就是网络数据采集。使用代码从网站收集数据,当时对我来说是一个完全陌生的概念,但它是最合理、最容易获取的数据来源之一。...

24820
来自专栏为数不多的Android技巧

请不要滥用SharedPreference

SharedPreference是Android上一种非常易用的轻量级存储方式,由于其API及其友好,得到了很多很多开发者的青睐。但是,SharedPrefer...

25540
来自专栏阮一峰的网络日志

代码覆盖率工具 Istanbul 入门教程

测试的时候,我们常常关心,是否所有代码都测试到了。 这个指标就叫做"代码覆盖率"(code coverage)。它有四个测量维度。 行覆盖率(line co...

35040

扫码关注云+社区

领取腾讯云代金券