Are there some good and modern alternatives to Javadoc? [closed]

I have created a Markdown (java) Doclet which will take source comments in Markdown formatted text and create the same HTML Javadocs.

The new doclet also does some restyling on the text, but the HTML generated is not changed at this stage.

That goes some way to address the HTML-in-java-commenting issues which is probably the biggest usability problem with current Javadoc.

I don't think that the concepts of Javadoc are outdated. As far as i can see, these concepts are rooted years ago in a product named doxygen, which is still available for other languages (i.e. Objective-C where it is heavily used). Even this has it's predecessors - have a look at the programming environment used by Donald Knuth to create TeX (Literate programming).

Nevertheless it is a intriguing idea to have a single source for program code and documentation.

Besides of that, the presentation of the documentation can be customized to your special needs using a plug-in system supported by the JavaDoc tool. You might provide a plug-in (as we do) that publishes directly into a database which is directly accessible via web. Using collaborations anyone can provide additional comments or clarifications to the documentation that might find their way back into the original source.

Javadoc is the best source code auto-documentation generation system I've ever seen. Large part of that is that it's so simple - I can browse javadocs even with my 5 year old cell phone if I want to! While I agree that a bit of a facelift could be in order and especially JDK is a pain to browse through, I wouldn't dare reinventing the wheel entirely because what we currently have is a RESTful, easy to use solution for its purpose which works just about anywhere.

I recently got a mail forwarded that Sun is working on modernizing the Javadoc HTML output. From said mail:

We are proposing improvements to javadoc/doclet for JDK7. The project wiki page is located at http://wikis.sun.com/display/Javadoc/Home. As a part of the proposed improvements, the UI of the javadoc output will be revamped. The new design screenshots are uploaded to the project wiki. The javadoc output markup will be modified to be valid HTML and WCAG 2.0 compliant.

So there is definitely still work going on there, even if somewhat late. However, in my eyes one of the biggest drawbacks of Javadoc is its very close coupling with HTML. Many classes have Javadoc which includes literal HTML and relies on the output being HTML, too. Unfortunate, but this won't change anytime, I think. Still, this means that developers are free to include whatever they want in HTML there which might as well be invalid, non-well-formed, etc. So adapting the output from the javadoc tool is only one part of this, the other won't and can't change and thus remains.

As for browsing documentation I also find the HTML documentation a little unwieldy. I usually use the Javadoc view in Eclipse. It has drawbacks as well (slow and you can't really search) but it's Good Enough™ for most things.