Tip: Javadoc as XML

原创 2005年05月26日 08:17:00
 
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

Android 开发 Tip 2 -- 多主题下drawable.xml使用?attr的问题

转载请注明出处:http://blog.csdn.net/crazy1235/article/details/51820937多主题下引用attr的问题。 在5.0以下手机,如果drawable xm...

AS3 操作XML,增加、删除、修改、查找

var i:Number=0;//用于下面循环 var webcontent:String="Sontin's Blog Welcome to 终吾一生"; var myXML:XML= ...

as 3.0 结合xml制作走马灯

  • 2008年01月30日 17:26
  • 55KB
  • 下载

as 3.0读取XML

  • 2013年05月08日 22:43
  • 8KB
  • 下载

Flash 新浪天气预报的xml文件 as3.0

package  {  import flash.events.Event;  import flash.events.EventDispatcher;  import flash.disp...

as3.0用xml调用图片相册

  • 2011年12月29日 11:55
  • 318KB
  • 下载

as3.0 饼形图 调用xml

  • 2010年06月27日 20:51
  • 1.02MB
  • 下载

as3读写本地xml/txt

/** * 读取本地配置文件xml * @param retrun xml */ public function readLocalXml():XML {...
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:Tip: Javadoc as XML
举报原因:
原因补充:

(最多只允许输入30个字)