What is XHTML Doclet?

XHTML Doclet is an alternative doclet for Javadoc. In a nutshell, it creates ouptut that is compliant with web standards and structured to allow for flexible styling, which offers enhanced control over output appearance.

Javadoc has two stages: (1) parsing the source code and creating a representative data structure, and (2) traversing the data structure and generating the documentation. The javadoc program handles the first stage, then sends data to a doclet (which usually extends com.sun.javadoc.Doclet, like XHTML Doclet does) for the second stage, as described on the Doclet Overview page. The doclet can then generate markup for the documentation in any desired format.

Why did you create it?

I can think of several reasons that prompted me to write a replacement doclet that creates valid XHTML:

  1. The standard doclet creates outdated and invalid HTML markup.
  2. The standard doclet creates poorly structured HTML markup.
  3. The standard doclet navigation needs some serious loving.
  4. The standard doclet CSS is kludgy, poorly-used, and ugly.
  5. It's nearly impossible to customize the output to my taste.
  6. Hard-coded inline CSS styles are so turn-of-the-century.
  7. Font tags and table-based designs are so last century.
  8. The standard doclet is complex and hard to maintain.
  9. To my knowledge, nobody else had written one yet.
  10. I can be somewhat obsessive and anal-retentive.

For reference, check out the Java 5 API docs. Not bad, but also not great†. I'm a big believer in good documentation, and I personally feel that making documentation look like you want it to should not be an exercise in frustration and futility. (Those who have tried with Javadoc will understand exactly what I mean.) This is especially important for documentation which I'll be reading for untold hours.

† Many programmers think there is absolutely nothing wrong with Javadoc's output. (“If it's good enough for James Gosling, it's good enough for me!”) If you're one of those people, you might just want to move along… There's nothing to see here.

How do I use it?

Any system with the Java JDK installed can use XHTML Doclet. Any recent version of Javadoc should be suitable. (See the next section for details.)

First, you'll want to download the JAR file containing the class files and resources. Place it in any location you find convenient and accessible for your documentation needs.

Then, add the following arguments to your current Javadoc command:

-doclet net.sourceforge.xhtmldoclet.Doclet
-docletpath {local path}/XHTML_Doclet.jar

If using an Ant Javadoc task, add the following tag nested inside a <javadoc> tag:

<doclet name="net.sourceforge.xhtmldoclet.Doclet" path="{local path}/XHTML_Doclet.jar"/>

These arguments tell Javadoc to use XHTML Doclet instead of the Standard HTML doclet.

  • The -doclet option refers to the class that acts as the starting point for the doclet.
  • The -docletpath option points to a directory or JAR file where Javadoc can find that starting class.

To get the exact parameters for your system, you can also double-click the JAR file once you've saved it where you want it.

What are the features?

Most Java 1.5 language features are currently supported, and more refinements and additions are planned. The majority of the features from the standard doclet are also included, although many are not fully implemented yet.

Ongoing development may utilize language features only present in Java 1.5 and beyond in order to make the doclet more robust and easier to maintain. (I figure if you care about web standards and aesthetics, you probably care about staying relatively current on Java, too.)

To understand the sweeping changes to the internal structure of the documentation, it's best to look at the source code of an example. Not only is the code XHTML-compliant, but the judicious use of headings, lists, divs, and IDs makes customizing the appearance a snap.

Release notes with more comprehensive details of the changes will be available on the project site in due course, but for the time being the focus is on making it work as intended.

What if I've found a bug?

Help us squash it—report it here. We'll do our best to remedy the situation at the first opportunity. Be sure to check existing bugs first to avoid duplication. (If you know how, helping pinpoint the bug in the code is even more useful!)

What if it's missing a feature I want?

By all means, request it here. We know that no single person can think of all the good ideas, so your feedback is welcome. Again, please check for duplicates first. Features are subject to consideration and approval—there are no guarantees of adoption.

What if I think it still looks ugly?

Beauty is a subjective thing, and we're all entitled to our own opinion. Aesthetic details can be amended using a customized CSS stylesheet by (1) specifying it as an argument to javadoc, or (2) replacing the stylesheet for existing documentation. Users are encouraged to make changes as they see fit to match the context of their site, etc.

If it still doesn't measure up to what you're looking for, have a go at making the output match your vision of what Javadoc should be. If you feel your modifications would be beneficial to the community as a whole, feedback and contributions are welcome, albeit with a disclaimer that they may not necessarily be incorporated. On the other hand, they might fit with the vision of this project and make it even better. In any case, this code is under the LGPL, so you can even create your own derivative and modify it as you see fit.

The code is fairly straightforward, with much of it having been refactored from the gory abstracted mess of the standard doclet source code, which jumps around a handful of packages and a myriad of classes. With regard to the original output, the intent is to remove the things that don't need to be there and add the things that should be there.

What about plans for the future?

XHTML Doclet ties in with the Java Doclet API, as well as some internal utility classes available with the Java source code (com.sun.tools.doclets.internal.toolkit and children). As those tools are updated for new revisions of the Java language, XHTML Doclet can evolve right along with them.

Also, if Sun should ever take an interest in using the code, it would be a simple matter of changing the base package to com.sun.tools.doclets.formats.xhtml and integrating it into the source tree. (There are some distinct changes in XHTML Doclet that depart from the architecture of the Standard doclet, but it would work just fine.)

If you find XHTML Doclet to be valuable and wish to help further its development, you can also support the project monetarily. All donations are directed exclusively towards development of XHTML Doclet. Thanks!

Support This Project