Eitan Suez's Blog

Community: Java Tools Archives

No docdoclet for xdoclet?

Xdoclet did a very good thing: not only did they use a doclet-like mechanism to produce xml files and other artifacts to make j2ee and web development easier, they gave us a better design than javadoc in that the code generation is template-driven. My understanding is that xdoclet v1 used the xdt template engine while xdoclet 2 is now based on generama (where one can choose to use velocity or freemarker template engines). All this is now old history.

The interesting thing to me is that the javadoc standard doclet (which remains the defacto standard) still doesn't employ this design pattern. That is, it generates its html pages in code without resorting to templates. This makes it difficult for anyone to enhance these pages or come up with alternative pages ( modifying stylesheet.css doesn't quite cut it :-) ), as Kohsuke found out recently (see his recent blog entry).

So another way to put it is that a rich variety of plugins exist for xdoclet such as ejbdoclet, webdoclet, hibernatedoclet, etc.. but the glaring omission to me is that there is no "docdoclet", that is an xdoclet plugin for generating javadocs.

One of the things I did when I developed ashkelon a number of years ago was to take apart the standard doclet and produce the jsp template equivalent thereof. So hiding in the ashkelon project under htdocs/basic reside these templates.

I'm now thinking that it would be very desirable to have an xdoclet-like mechanism for producing alternate javadoc ui's; ones with ajax features, for example. I can think of many scenarios where a developer might want to add a section to a class's doc page, just like kohsuke did for jaxb 2.

I've started working on adding an feature/option to ashkelon to alternatively produce static docs from the same jsp templates that i use to produce the dynamic version of ashkelon (less the dynamic features such as search). I actually have a working prototype. Maybe once this feature is finished and tested and I cut a new version of ashkelon, it might help folks more easily extend the production of javadocs in interesting ways.

This work is licensed under a Creative Commons License.