开发者社区> meteoric> 正文

Ant+JSDocTookit生成Javascript文档

简介: 文章转自:hikejun.com/blog/?p=33   需要备上下面三样东西 JSDocTookit http://code.google.com/p/jsdoc-toolkit/ JSDocTookit Ant Task http://code.
+关注继续查看

文章转自: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的官方文档吧,利用其来促使我们写出更高效优雅的前端代码并惠及更多的人才是一大步。

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
doctype文档类型|学习笔记
快速学习doctype文档类型
33 0
ML之FE:基于load_mock_customer数据集(模拟客户)利用featuretools工具实现自动特征生成/特征衍生
ML之FE:基于load_mock_customer数据集(模拟客户)利用featuretools工具实现自动特征生成/特征衍生
59 0
使用typeDoc快速生成开发文档
使用typeDoc快速生成开发文档
153 0
SpringBoot 实战:通过 BeanPostProcessor 动态注入 ID 生成器
在分布式系统中,我们会需要 ID 生成器的组件,这个组件可以实现帮助我们生成顺序的或者带业务含义的 ID。
49 0
Next.js v4.1.4 文档中文翻译
最近想稍稍看下 React的 SSR框架 Next.js,因为不想看二手资料,所以自己跑到 Github上看,Next.js的文档是英文的,看倒是大概也能看得懂, 但有些地方不太确定,而且英文看着毕竟不太爽你懂得,所以在网上搜了几圈发现好像好像还没有中文翻译,想着长痛不如短痛, 索性一边看一边翻译,自己翻译的东西自己看得也爽,不过毕竟能力有限,有些地方我也不知道该怎么翻译才好,所以翻译得不太通畅, 或者有几句干脆不翻译了。
7664 0
用WinDbg分析Debug Diagnostic Tool生成的Userdump文件
1、下载WinDbg(Debugging Tools for Windows):http://www.microsoft.com/whdc/devtools/debugging/default.mspx 2、安装WinDbg 3、运行WinDbg 4、配置Symbol文件路径: File>Symbol File Path,输入:SRV*c:\websymbols*http://msdl.
907 0
使用Docker生成SSL证书
本文讲的是使用Docker生成SSL证书【编者的话】学习如何使用Docker生成SSL证书,而不是在主机上生成。
2500 0
+关注
423
文章
0
问答
文章排行榜
最热
最新
相关电子书
更多
JS零基础入门教程(上册)
立即下载
性能优化方法论
立即下载
手把手学习日志服务SLS,云启实验室实战指南
立即下载