您的位置：首页 > 编程语言 > Java开发

Tip: Javadoc as XML

2005-05-26 08:17 399 查看

Tip: Javadoc as XML

Contents:

Create HTML from the XML

Related content:

Java theory and practice: I have to document THAT?

Documenting your project using the Eclipse help system

Subscriptions:

dW newsletters

Use Javadoc XML output for reports

Level: Intermediate

Jack Herrington (jack_d_herrington@codegeneration.net)
Editor-in-Chief, Code Generation Network
14 Apr 2005
A lot of value is locked up in your Java code: all your classes and interfaces, as well as their instance variables and methods. You can use these data to create documentation, to build code generators, or to provide metrics for project reporting.The Javadoc tool is a very well-factored application. Many people think it?s just a program that creates HTML from reading the code and comments in a set of Java™ files. But in reality, the tool is divided into two sections. The first is the code-analysis engine, which parses the code and the comments. The second generates the HTML, but as it turns out, you can change that section with extensions called doclets.
For this tip, I use JELDoclet (see Resources) to generate an XML output file from a set of test Java files. Then, I use XSL to format the XML into a simple HTML file that demonstrates what data are in the XML file.
After downloading JELDoclet, I run it on a set of files using the following syntax:

javadoc -doclet JELDoclet -docletpath .. *.java

The

test

directory of JELDoclet includes a set of test Java files. This command parses all the Java files in the test directory and creates a file called out.xml, which contains all the information in the Javadoc tree. Listing 1 shows a portion of this output XML file.
Listing 1. The JELDoclet output XML file

<jel>
<class superclass="Object" name="MyInterClass">
<extend name="MyInterface">
</extend>
<comment>
My interface implemented
</comment>
<fields>
<field visibility="protected"
fulltype="java.lang.String"
type="String" name="_prot_string">
<comment>
A protected string
</comment>
</field>
<field visibility="public"
fulltype="java.lang.String"
type="String" name="_pub_string">
<comment>
A public string
</comment>
</field>
</fields>
<methods>
<constructor visibility="public" name="MyInterClass">
<comment>
A no-argument constructor
</comment>
</constructor>
<constructor visibility="public" name="MyInterClass">
<params>
<param fulltype="java.lang.String"
type="String" comment="A string."
name="aString">
</param>
...

The

jel

tag contains a series of

class

tags -- one for each class. Within the

class

tags are the fields, methods, and constructors. The XML file also includes the associated comments.
Create HTML from the XML
Your first step toward generating the HTML for this XML (in Listing 1) is to start with the base tag template in Listing 2.
Listing 2. The base HTML template

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet
xmlns:xsl=http://www.w3.org/1999/XSL/Transform
version="2.0">

<xsl:output method="html" />

<xsl:template match="/">
<html><head><title>XDoclet output</title>
<xsl:call-template name="css" />
</head>
<body>
<xsl:for-each select="/jel/class">

<h1>
<xsl:choose>
<xsl:when test="@abstract='true'">Interface:
<xsl:value-of select="@name" /></xsl:when>
<xsl:otherwise>Class
: <xsl:value-of select="@name" />
( <xsl:value-of select="@superclass" /> )
</xsl:otherwise>
</xsl:choose>
</h1>

<h2>Instance Variables</h2>
<xsl:apply-templates select="fields/field" />

<h2>Constructors</h2>
<xsl:apply-templates select="methods/constructor" />

<h2>Methods</h2>
<xsl:apply-templates select="methods/method" />

<hr/>
</xsl:for-each>
</body>
</html>
</xsl:template>

In the first section, I create the

html

root tag and the

head

section. Then, I iterate through every class in the input file. For each class, I output the class or interface name in an

h1

tag and apply templates for the

fields

constructors

, and

methods

. Then, I wrap it all up by closing the

body

and

html

tags.
The template for building the field HTML is very simple, as Listing 3 shows.
Listing 3. The field template

<xsl:template match="field">
<p class="field">
<xsl:value-of select="@visibility" />
<xsl:text> </xsl:text>
<xsl:value-of select="@type" />
<xsl:text> </xsl:text>
<xsl:value-of select="@name" />
</p>
</xsl:template>

Pretty simple stuff: I just output the visibility, the type, and the name. I bracket that in a

paragraph

tag with the

class

field, which I?ll use later in the CSS.
The method and constructor templates are similar to the field template, as Listing 4 shows.
Listing 4. The method and constructor templates

<xsl:template match="method">
<p class="method">
<xsl:value-of select="@visibility" />
<xsl:text> </xsl:text>
<xsl:value-of select="@type" />
<xsl:text> </xsl:text>
<xsl:value-of select="@name" />(
<xsl:apply-templates select="params" />
)</p>
</xsl:template>

<xsl:template match="constructor">
<p class="method">
<xsl:value-of select="@visibility" />
<xsl:text> </xsl:text>
<xsl:value-of select="@name" />(
<xsl:apply-templates select="params" />
)</p>
</xsl:template>

The only trick here is that I need to output the list of parameters to each constructor or method. I do this with the

xsl:apply-templates

tag, which finds the correct template for the

params

tag -- in this case, the template shown in Listing 5.
Listing 5. The params template

<xsl:template match="params">
<xsl:for-each select="param">
<xsl:if test="position()>1">, </xsl:if>
<xsl:value-of select="@type" /><xsl:text> </xsl:text>
<xsl:value-of select="@name" />
</xsl:for-each>
</xsl:template>

The interesting part here is that I want commas between the parameters in the list, so I use the

xsl:if

directive to insert a comma only if I?m on the second parameter or later.
The last part of the XSL template is the CSS portion, which makes the output a bit more readable (see Listing 6).
Listing 6. The CSS template

<xsl:template name="css">
<style>
body { font-family: Arial, Verdana, sans serif;
font-size: small; }
.method, .field { padding-left:50px; }
</style>
</xsl:template>

</xsl:stylesheet>

Use sans-serif fonts like Arial or Verdana to make the output more readable. You might use Courier, but I think it makes the page look drab and gives the impression that it was written on an old typewriter. The final output looks like that in Figure 1.
Figure 1. The resultant HTML in a browser

Summary
Formatting HTML is just one of the things you can do with XML output from the Javadoc tool. You can use the information in the Javadoc tree (exported here as XML) to power code generators, as XDoclet does. You can perform code-reference analysis and refactoring like Eclipse or IntelliJ. You can also get metrics on your code base. Having a complete, structured representation of your Java code in XML is a powerful tool that can help increase your productivity.
Resources
Visit the XSL standards site at the W3C, a handy reference to XSL technologies and standards.

Check out the XPath page at the W3C, which provides version and standard information.

Download Saxon, the popular XSL processor that was used in the creation of this article.

Read Michael Kay?s XSLT 2.0 Programmer's Reference, the bible of XSLT. It?s a fantastic introduction and a valuable reference work.

While you're at it, pick up XPath 2.0 Programmer's Reference by Michael Kay -- the ultimate reference by the man who wrote the W3C specification.

Read Code Generation in Action by Jack D. Herrington, which covers generating code for a wide variety of targets not limited to database access.

See the Javadoc home page for more information about Sun Microsystems? Javadoc tool.

Find out more about JELDoclet, the Doclet extension used in this article to create the input XML.

Explore Doclet.com, a repository of Doclet extensions for the Javadoc tool.

Try XDoclet, the acclaimed code generator that was originally based on the Javadoc framework.

Find hundreds more XML resources on the developerWorks XML zone.

Learn how you can become an IBM Certified Developer in XML and related technologies.

About the author
An engineer with with more than 20 years of experience, Jack Herrington is currently Editor-in-Chief of the Code Generation Network. He is the author of Code Generation in Action. You can contact him at jack_d_herrington@codegeneration.net.

http://www-128.ibm.com/developerworks/java/library/x-tipjdoc/index.html

内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理

标签： javadoc xsl constructor output reference generation

相关文章推荐

新的分享

章节导航