Creator of the Apache Tapestry web application framework and the Apache HiveMind dependency injection container. Howard has been an active member of the Java community since 1997. He specializes in all things Tapestry, including on-site Tapestry training and mentoring, but has lately been spreading out into fun new areas including functional programming (with Clojure), and NodeJS. Howard is a DZone MVB and is not an employee of DZone and has posted 79 posts at DZone. You can read more from them at their website. View Full User Profile

Extending JavaDoc

05.23.2011
| 4293 views |
  • submit to reddit

I don't think I've seen a piece of code more poorly designed for extension, and more in need of it, than JavaDoc. I'm in the process of removing Tapestry's Maven-based component report (as part of an overall move from Maven to Gradle). My goal is to merge what currently comes from the component report directly into the JavaDocs.

My first approach was to extend the built-in HtmlDoclet , the one that generates the every-day HTML report. Good luck with that ... it's like a field guide to anti-patterns for preventing extensibility. Here's an example:

public class HtmlDoclet extends AbstractDoclet {

/**
* The global configuration information for this run.
*/
public ConfigurationImpl configuration =
(ConfigurationImpl) configuration();


/**
* Create the configuration instance.
* Override this method to use a different
* configuration.
*/
public Configuration configuration() {
return ConfigurationImpl.getInstance();
}

...
}

public class ConfigurationImpl extends Configuration {

/**
* Constructor. Initialises resource for the
* {@link com.sun.tools.doclets.MessageRetriever}.
*/
private ConfigurationImpl() {
standardmessage = new MessageRetriever(this,
"com.sun.tools.doclets.formats.html.resources.standard");
}

public static ConfigurationImpl getInstance() {
return instance;
}

...
}

So, HtmlDoclet commits the cardinal sin of down-casting from the interface to the implementation class, and ConfigurationImpl is effectively final, as its only constructor is private. But you are encouraged to override the configuration anyway (recommended only if your goal is to throw a ClassCastException).

JavaDoc is old. The HtmlDoclet is just ... tired. Someone failed to tell these folks about XML and XSL, for example ... or about HTML and CSS, for that matter. JavaDoc is screaming out to be a tool that generates an XML representation of Java source content that can then be transformed into an HTML document tree via XSLT. I've seen an abandoned project along those lines. Perhaps in my spare time ... it would be a fun little side project to create that, and create a really world-class JavaDoc.

In any case ... I've been forced to impose the use of a @tapestrydoc tag on component classes that wish to be documented. Not the end of the world, but not backwards compatible either (though the Tapestry 5.2 Maven component report will continue to work with Tapestry 5.3, so that's not a deal-breaker).

From http://tapestryjava.blogspot.com/2011/05/extending-javadoc.html

Published at DZone with permission of Howard Lewis Ship, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Tags:

Comments

Thomas Mueller replied on Tue, 2011/05/24 - 1:15am

If you don't like it, make it better :-) It's actually not that hard to write your own doclet.

> Someone failed to tell these folks about XML and XSL

Nice joke!

Lance Semmens replied on Tue, 2011/05/24 - 3:50am

XSLT is the most horrible thing I have ever had the displeasure of programming in. Freemarker has excellent XML support (including XPATH) and is faster, requires less memory and in my view is 10x easier to write and maintain than XSLT.

Nicholas Whitehead replied on Tue, 2011/05/24 - 6:54am

I have to agree; the API is fairly poor. My wish list would be for javadoc tags to be promoted to full annotations, with configurable retention. In addition to supporting javadoc generation from bytecode, runtime retention would allow for superior meta-data which would offer useful and redundancy eliminating support for descriptive annotations like JMX.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.