自定义java Doclet的调试

本文介绍如何通过自定义Javadoc Doclet简化接口文档的生成流程。通常在更新代码后同步更新文档会带来额外的工作负担,因此作者选择通过编写自定义的Doclet来解决这一问题。文章详细解释了Doclet的概念及其工作原理,并提供了实现自定义Doclet的具体步骤。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

         工作中经常需要对外提供接口,这个时候接口的文档就非常麻烦,同时是维护在wiki或者其他地方,但是修改代码之后很可能没有及时更新wiki,造成很多交流的成本。所以想直接通过javadoc 生成接口文档的方式。发现maven提供的javadoc插件,但是原生的Doclet不能满足我的要求。所以需要自己定义doclet。来看下Doclet的定义:

Doclet 是用 JavaTM编程语言编写的程序,它用 doclet API 指定 Javadoc 工具的输出内容和格式。缺省情况下,Javadoc 工具用 SunTM 提供的“标准” doclet 来生成 HTML 形式的 API 文档。然而,用户也可用自己的 doclet 根据个人喜好自定义 Javadoc 输出。用户可以利用 doclet API从头开始编写 doclet,也可以对标准 doclet 进行修改,以适合自己的需要。
下面是创建和使用自己的 doclet 的基本步骤:

1. 编写用来构成 doclet 的 Java 程序。为使用 doclet API,该程序应导入 com.sun.javadoc.*。程序的入口点是一个带有 public static boolean start 方法的类,它将 RootDoc 作为参数。
2. 编译 doclet。可以使用 Java Development Kit 的编译器 javac 来编译它。
3. 用 -doclet <YourDoclet> 选项运行 javadoc 工具,生成 doclet 指定的输出。

doclet API 类文件在 JDK 软件的 lib/tools.jar 文件中。当编译 doclet 和使用自定义 doclet 时,tools.jar 必须在类路径上。为此,可以对 javac 和 javadoc 使用 -classpath 选项。 

      这里说到了doclet需要使用tools.jar,在使用ide比如idea时在project setting中对jdk的classpath加上tools.jar的路径就可以了。但是这货调试太麻烦了,根据网上的资料只能在外面先编译好你的Doclet ,然后用javadoc -doclet 指定编译好的doclet。但是这样不能debug doclet程序,重新找了下网上的资料加上自己的时间,发现可以这样搞

public class APIDoclet {


    public static boolean start(RootDoc root) {
        ClassDoc[] classes = root.classes();
        for (int i = 0; i < classes.length; ++i) {
            System.out.println(classes[i]);
        }
        return true;
    }


    public static void main(String[] args) {
        String[] docArgs = new String[]{"-doclet", APIDoclet.class.getName(), System.getProperty("user.dir") + "/src/main/java/" + "com/hz/yk/concurrent/aqs/BooleanMutex.java"};
        com.sun.tools.javadoc.Main.execute(docArgs);
    }

}

哈哈哈,这下可以打断点了

附上doclet 的资料:

http://dadi520.iteye.com/blog/545897

XDoclet 是一个通用的代码生成实用程序,是一个扩展的Javadoc Doclet引擎,它允许您使用象 JavaDoc 标记之 的东西来向诸如、方法字段之的语言特征添加元数据。随后,它利用这些额外的元数据来生成诸如部署描述符源代码之的相关文件。可以让你创建自己 的javadoc @tags进而利用XDoclet中的Templet enging基于这些@tags生成源代码或其他文件(例如xml的deployment descriptors)。 XDoclet 继承了 JavaDoc 引擎的思想,允许根据定制 JavaDoc 标记生成代码其他文件。当然,XDoclet 也可以访问整个解析树。这样,它就可以访问的包结构的方法。 Xdoclet由三个主要组件组成、Xjavadoc引擎,Xdoclet引擎模块。模块又由任务、子任务、标记处理程序模板。 XJavaDoc 引擎:XJavaDoc 解析 Java 源文件,然后构建有关语言特征(包、方法字段)以及元数据的信息树。XJavaDoc 引擎通过一个易于使用的 API 提供访问。该 API 提供了与带有一些额外特征的 JavaDoc API 相同的信息,这些额外特征与存储及读取元数据以及其他结构相关联。XJavaDoc 增加了在运行时修改 JavaDoc 标记的能力。这样就可以推断元数据,并可以将其缺省值设为比较合理的值。 XDoclet 引擎:XJavaDoc 引擎读取标记,这些标记组成了的元数据结构。XDoclet 引擎使用来自 XJavaDoc 引擎的信息,来生成支持文件(源代码部署描述符)。XDoclet 提供了一个优秀的模板生成引擎,该引擎将模板转换成一个或多个支持文件。XDoclet 有一个模块装入程序,它动态地装入用 xdoclet.xml 文件(包含在模块的 jar 文件中)指定的 XDoclet 模块。 您无需创建模块就可创建模板。每个顶级 XDoclet Ant 任务都有执行任意模板的能力,以此替换随模块一起提供的模板。 模块引擎:模块由任务、子任务、标记处理程序模板组成。 目前的版本可以为web(web.xml)、ejb、struts(struts-config.xml)、webwork、hibernate (mapping file)、jdo、jmx等等生成描述文件、源码等,XDoclet提供了ant的任务target支持,完全通过ant来完成任务。 我们只须在项目中引入xjavadoc-1.1.jar、xdoclet-hibernate-module-1.2.3.jar等等所需要的jar包就可以了。以下是我在项目中写的一些。 例如 action …… import org.apache.struts.action.ActionForward; /** * * @author yangjuqi 2007-06-13 * @struts.action name="biddingForm" path="/carriageBidQuery" validate="false" * @struts.action-forward name="success" path="ship.bid.carriage.search" */ public class CarriageBidQueryAction extends BaseAction { protected ActionForward execute(BActionContext context) throws Exception { System.out.println("------- CarriageBidQueryAction execute -----"); String markey=context.getRequest().getParameter("markey"); if(markey==null || markey.equals("0")){ return this.queryBiddingAll(context); } return null; } …… 在struts-config.xml中生成如下代码: <action path="/carriageBidQuery" type="com.baosight.baosteel.bli.lgs.bid.struts.action.CarriageBidQueryAction" name="biddingForm" scope="request" unknown="false" validate="false" > <forward name="success" path="ship.bid.carriage.search" redirect="false" /> </action> 例如 model(与数据库中的表对应) …… /** * @author yangjuqi 2007-07-18 * * @hibernate.class table="LGS_INVITED_CARRIER" */ public class InvitedCarrierModel implements java.io.Serializable { private Long id; private String carrierCompanyCode; private Long biddingId; /** * @hibernate.property column="BIDDING_ID" type="long" */ public Long getBiddingId() { return biddingId; } public void setBiddingId(Long biddingId) { this.biddingId = biddingId; } …… 在指定的目录中生成文件InvitedCarrierModel.hbm.xml,代码如下: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE hibernate-mapping PUBLIC "-//Hibernate/Hibernate Mapping DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd"> <hibernate-mapping> <class name="com.baosight.baosteel.bli.lgs.model.InvitedCarrierModel" table="LGS_INVITED_CARRIER" > …… <property name="biddingId" type="long" update="true" insert="true" column="BIDDING_ID" /> …… </class> </hibernate-mapping> 在Build.xml中的关于Xdoclet的配置如下: <target name="generateHibernateConf" depends="init"> <taskdef name="hibernatedoclet" classname="xdoclet.modules.hibernate.HibernateDocletTask"> <classpath refid="classpath" /> </taskdef> <hibernatedoclet destdir="${conf.hibernate}"> <fileset dir="${src}"> <include name="**/*.java" /> </fileset> <hibernate version="3.0" /> </hibernatedoclet> </target> <target name="generateStrutsConf" depends="init"> <taskdef name="webdoclet" classname="xdoclet.modules.web.WebDocletTask"> <classpath refid="classpath" /> </taskdef> <webdoclet destdir="${conf.struts}"> <fileset dir="${src}" includes="**/*.java" /> <strutsconfigxml version="1.2" destdir="${conf.struts}" mergeDir="${conf-merge.struts}" /> </webdoclet> </target> 像@hibernate.clas、@hibernate.property、@struts.action-forward等等这些特定的注释标签需要去查XDoclet的相关文档了,Xdoclet对目前流行的多种框架、技术都提供了相关的支持。 这样,我们就能在使用ant编译工程的同时,使Xdoclet为我们生成相关的配置文件了。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值