Blog About Contact

Open Source » markdown-doclet

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.

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 damn 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 be almost impossible to read in the place where you're most likely to read it - in the code.

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! :)

About the Author

Richard Nichols is an Australian software engineer with a passion for making things.

Follow him on twitter or subscribe by RSS or email.