Skip to main content

No docdoclet for xdoclet?

Posted by eitan on September 23, 2005 at 9:38 PM PDT

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.

Related Topics >>