天道酬勤

Mama said, life's like a box of chocolate, you never know what you gonna get next.

Tip: Javadoc as XML

 
Tip: Javadoc as XML
89 KBe-mail it!
Contents:
Create HTML from the XML
Summary
Resources
About the author
Rate this article
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
The resultant HTML

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

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

阅读更多
个人分类: Java
想对作者说点什么? 我来说一句

Tip类demo Tip类demo

2017年09月30日 147KB 下载

没有更多推荐了,返回首页

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭