I spent some spare time this week creating a mash up of sorts… a “markdown” doclet for Javadoc.

Markdown-Doclet Project on Google Code

Markdown is a light-weight markup language which reads much like plain-ASCII-formatted-text, as opposed to HTML which reads like… well HTML.

In fact HTML is pretty damny unreadable, which is why is frustrates me to see developers putting a whole <ul><li>bunch</li><li> of</li><li> html</li></li> <li>tags</li></ul> in their code’s Javadoc comment boxes only to rended it almost impossible to read in the place where you’re most likely to read it (in the code).

The idea of the Markdown doclet is that you can write simple (markdown) text into your Javadoc comments and they will be translated nicely into HTML in your final Javadoc output.

The hardest part of this doclet was figuring out how the hell to patch the standard Sun doclet post Java 1.5. In fact the answer to this is that you need to duplicate the whole damn thing, since they effectively stopped anyone using any part of the current class tree by putting a hard lock into the code.

I was quite suprised at how badly supported the whole Javadoc tool is by Sun. I would see Javadoc as being one of the best out-of-the-box features of the Java platform and probably one of the biggest reasons for it’s wide adoption in the early years.

Anyhow, I have basically glued together the (GPL’ed) Sun doclet (with some changes), MarkdownJ (a Java implementation of Markdown) and UMLGraph.

UMLGraph? – Well I love the UMLGraph doclet which embeds UML class diagrams into your Javadocs. The UMLGraph doclet works by calling the Sun standard doclet and then doing some mods on the files that are generated, so the markdown doclet can work interchangeably with UMLGraph, albeit I had to patch UMLGraph to make that happen, since the Sun standard doclet doesn’t implement any standard interface which would allow a drop in replacement!

I hope other developers can make use of this doclet, and we can keep HTML in our browsers where it belongs!

Related posts:

1. markdown-doclet Updated to v2
2. 5 Reasons Why NetBeans Rocks
3. The 5 Minute Guice Primer
4. Automatic Javascript and CSS Compression For Java Webapps