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

Display XML in a javadoc

Let's say you have a comment like this /** * To use this class use this XML * * * foo * ...
  • mangmang2012
  • mangmang2012
  • 2014年08月02日 09:08
  • 724

怎样创建界面提示TipText

为了对界面功能有一个详细的描述而又不将这些描述语言写到界面上,此时我们就需要鼠标提示。当鼠标放到某一个控件上时,会弹出一个小的提示框来说明该控件的作用。添加鼠标提示的步骤可分为如下几步:1.在类中声明...
  • jonathanlin2008
  • jonathanlin2008
  • 2008年08月05日 09:41
  • 1168

maven 打包报错 生成javadoc 时有问题

项目是基于maven管理的,一直打包都好着呢,今天打包莫名奇妙的报了一大堆错误[ERROR] java.lang.ClassCastException: com.sun.tools.javadoc.C...
  • ningxuezhu
  • ningxuezhu
  • 2014年09月24日 14:01
  • 12984

用javadoc命令,生成api帮助文档

昨天下午开始
  • watermusicyes
  • watermusicyes
  • 2014年05月10日 10:55
  • 4979

CSS实例:非常不错的鼠标悬停TIP效果

我们可以为我们的链接加上这样的效果,以更加体现网页的亲和力与易用性。我们也可以在提供下载的链接下提供这样的tip提示。我们看这样的鼠标悬停TIP效果是如何实现的。看下面的XHTML代码: ...
  • ufojoan
  • ufojoan
  • 2013年07月30日 17:53
  • 1688

流行的jquery 提示插件 tip

信息提示虽然是小东西,但是在网站设计中却起到了巨大的作用。如果你网站的信息提示做的好,会给访客留下非常深刻的印象。下面有30个非常流行的jQuery信息提示插件,希望对各位有所帮助。记住,所有的这些都...
  • yibing548
  • yibing548
  • 2015年05月12日 11:19
  • 1263

Javadoc中显示xml

直接在Javadoc中写xml是不会被显示的,可以这样写:     *      * {@code      *      *      *      * ...      * ...
  • DHEEP
  • DHEEP
  • 2010年12月02日 10:58
  • 387

Javadoc使用

1. 概要javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说,只要在编写程序时以一套特定的标签作注释,在程序编写完成后,通...
  • u010297957
  • u010297957
  • 2016年04月19日 15:21
  • 2452

你不知道的Eclipse用法:使用Javadoc导出项目的API文档

使用Javadoc导出项目的API文档
  • ZJDWHD
  • ZJDWHD
  • 2016年08月31日 15:32
  • 2124

Android Gradle配置自动生成JavaDoc

在Build.gradle中添加下面内容task javadoc(type: Javadoc) { source = android.sourceSets.main.java.srcDirs...
  • cooljean
  • cooljean
  • 2015年08月31日 15:34
  • 2565
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:Tip: Javadoc as XML
举报原因:
原因补充:

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