Sharing structured data

XML Magazine

Subscribe to XML Magazine: eMailAlertsEmail Alerts newslettersWeekly Newsletters
Get XML Magazine: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

XML Authors: Jayaram Krishnaswamy, Chris Pollach, Jason Bloomberg, Peter Silva, Mehdi Daoudi

Related Topics: XML Magazine, Java Developer Magazine

XML: Article

Writing XML-Friendly Java Documentation

Writing XML-Friendly Java Documentation

It's there in every how-to-learn-Java book you pick up, right in the first chapter: a brief section about documenting your Java code. Like any good programmer, you probably flipped through those pages pretty quickly and said, "I'll get back to this later." But you never did, did you? No. Instead you plunged right into writing cute little applets and then bigger applications and pretty soon you were a Java guru. Documentation was never part of the deal.

It's time for you to get back to thinking about Java documentation. Recent trends in the Java marketplace are making Java documentation more and more necessary. The rise in demand for application servers and third-party Enterprise JavaBeans means that there will be a lot of developers working with code that they didn't write themselves. If the primary benefit of using EJBs is a reduction in development time, then a lack of quality Java documentation practically eliminates that advantage.

Another reason that Java documentation is so important is the volatility of the current job market. The accelerated hiring and high turnover in high-tech companies means that the project you're working on now will probably pass through many hands ­ if it hasn't already ­ before it's released. How else will you communicate your intentions to future developers except through clear and concise documentation?

The engineers at Sun were quite clever when they first released Java. They incorporated the Javadoc standard, which generates class documentation from source code, into the Java Development Kit from the very beginning. For those of you who didn't even read the first chapter of your Java books, Javadoc parses through your source code and creates HTML files that document every method, property and constructor of your classes. Even if you don't go beyond the basics of writing a Java class, Javadoc will create a very simple HTML file that outlines each of these features.

But the true strength of Javadoc is what the developer puts into it. Using special "tags," developers can specify the return types of methods, the exceptions that are thrown, references to other Javadoc files and even the version and author of the class itself.

A recent innovation makes Javadoc even more powerful than it already is. Leading vendors in the Java community are adopting Flashline's new JavaDox standard for Java documentation. The information that was once stored in HTML is stored in the XML (eXtensible Markup Language) format. The difference in the results is dramatic. I've included two different representations of the same method, Integer.parseInt(Strings). The HTML format (Listing 1), while easily viewable in a Web browser, is practically unreadable in its source. The tags don't convey any information besides how the data is to be formatted. The XML (Listing 2) is concise and easy to understand even if you don't have knowledge of the Document Type Definition (DTD) that defines the rules of creating a JavaDox file. The XML file can be used for many different purposes (including translating it into HTML files with no noticeable difference to the end user), while the HTML files are useful only when viewed in a browser.

There are many other benefits to storing this information in XML. Developers can search across packages, even from different vendors, for the information they need. One of the strengths of XML is that it allows contextual searches. Instead of just searching for any instance of java.util.Vector, you can specify that you'd like to find all methods that return java.util.Vector.

JavaDox also reduces the plentiful number of HTML files that Javadoc creates into one XML file, which can be formatted in many different ways. XML separates the content from the format, which means that Java documentation can be displayed in any conceivable style, from HTML to Acrobat files to PowerPoint presentations to anything you can imagine.

Which leads us to the greatest strength of XML storage: it's nonproprietary. In these days of foul-calling by the Department of Justice, XML is truly the people's tool. Anyone can write an application that reads XML files since it's text-based and easily readable. And with the abundance of XML tools and class libraries, anyone can easily create an XML-ready application.

This is what makes JavaDox exciting. (Trust me on this.) Take me as an example. I do almost all of my coding in Borland's JBuilder. Whenever I type the name of a class followed by a period, a pop-up box appears with a list of all properties and methods that I have access to. JBuilder does this through a combination of introspection and simple code parsing. But imagine a tool that can pull up not only a list of available methods and properties, but also brief descriptions, sample usage and references to other resources. You'll never again be stumped by the arcane intricacies of Java I/O or JNDI; it'll all be at your fingertips.

With all the advantages that XML has over HTML, it's inevitable that Java documentation will continue to move toward XML. That's why it's important now to write XML-friendly Java documentation. Following are some key points to remember:

  • Document every possible feature that you can. How many times have you been working with a class, and you find a method that needs a string as one of its parameters? How many times have you wondered what that string was supposed to be?

Is it a filename, a system property or the name of your first pet? In Javadoc and JavaDox you can comment on the function of any feature of your class, including parameters, return types, overridden methods and deprecated methods. Take advantage of this, and make your fellow developers happy.

  • But don't comment the obvious. Many times a brief sentence is all the explanation you need. If you've written good, self-documenting code, then, when a method's signature needs a string called fileName, you can assume that developers will know that what they need to pass is, in fact, a file name. (Of course, if it isn't, you've got bigger problems.) In these situations write comments that go beyond the obvious; explain what sort of file your method expects, or explain how this method will manipulate the file.
  • Follow Sun's Javadoc-style conventions. The first sentence of any description should be brief, and should summarize the functionality of the feature that it's documenting as succinctly as possible. This is especially important in JavaDox, because all descriptions are broken into <briefdescription> and <fulldescription> tags. Write in the third person ("Gets the label") as opposed to the second person ("Get the label"). Begin method descriptions with a verb phrase as opposed to "This method...." For additional style conventions visit
  • Remember that your documentation may not always be displayed in a browser. Javadoc allows you to embed HTML in your source code. To make your documentation truly XML-friendly, you should avoid this luxury. Since XML formats such as JavaDox can be easily repurposed, there's no telling where or in what format your Java documentation will be displayed. Your best bet is to use HTML sparingly. For example, if you wish to refer to an article published on a Web site, you may have no option but to create a hyperlink.

But try to rethink how you structure the information in your comments and avoid using tables, lists and images except when unavoidable.

  • If you do use HTML, make sure that it's well formed. While most applications of JavaDox don't parse through sections where they expect HTML to be embedded, it doesn't hurt to make sure that your HTML fits in with XML standards. In case you aren't familiar with XML, the most important thing about any XML document is that it be well formed. This means that each tag must be nested correctly, and that all tags must eventually close. In other words, <B><I>Hello</I></B> is well formed, while <B><I>Hey there</B></I> is not, because the tags are nested incorrectly. Closing all tags, however, can seem somewhat counterintuitive, especially with tags that you don't usually think of as needing to be closed. For example, instead of <HR>, you should use either <HR></HR> or <HR/> (the latter is preferred) if you wish to put a horizontal rule in your documentation. The scope of this article prevents me from going into this in detail, but an excellent place to start if you want to learn more about well-formed XML is Elliotte Rusty Harold's XML Bible (IDG Books).
  • Use descriptive HTML tags. <code>...</code> is preferred over <font face=courier>...</font> because it's closer to the concept of XML. Element tags should be self-describing and should reflect the meaning of the data that they contain, as opposed to the presentation.
  • Don't include non-Unicode text in your source code. XML is only required to support the Unicode character set, and using any non-Unicode character may cause unintentional havoc. Not that you would anyway, right? You'd be hard-pressed to come up with a character that isn't available in Unicode, but programmers are a crafty bunch indeed.

This has been only a brief introduction to XML-friendly Java documentation. For more information on JavaDox, visit the JavaDox Web site at There you'll find the DTD that defines the structure of a valid JavaDox XML file, sample stylesheets, the JavaDox application that generates XML from your Java source code and the documentation for JDK 1.2 in JavaDox.

More Stories By Tim Moyle

Tim Moyle is a software developer and the
manager of developer relations at He's developed
Web-based e-commerce
solutions, including the creation of the first
auction-based outsourcing system for component development.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.