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

Answer 1

You might want to phrase that in a less agressive and overbearing manner. Most people don't care what a technical resource looks like, and "It's not Web 2.0 enough!" sounds like vapid marketroidspeak.

And what exactly would you consider "more usable"? Personally, I would definitely like a full text search and a better useage browser, and AJAX could probable help with those.

Well, the nice thing about JavaDoc is that it's the opposite of outdated - it's arbitrarily extensible. Why don't you go ahead and write a doclet that produces the kind of API doc you want?

Why nobody else has done that so far (which apparently is the case) is anyone's guess - maybe nobody else feels as strongly about it as you.

Answer 2

Does anyone know, if there some plans to evolve Javadoc, in a somehow-standardized way?

The corresponding JSR (JSR 260), which specifies enhancements to Javadoc, has been voted out of JDK 7 (for now). An overview of what was planned (from this site):

Upgrade Javadoc to provide a richer set of tags to allow more structured presentation of Javadoc documentation. This JSR covers: categorization of methods and fields, semantical index of classes and packages, distinction of static, factory, deprecated methods from ordinary methods, distinction of property accessors, combining and splitting information into views, embedding of examples and common use-cases, and more.

The overall outlook for JDK 7 is pretty grim.

Answer 3

Personally I still find Javadoc to be very useful. Especially since it is standardized. I don't know of any major documentation style that I find easier to navigate (that might very well be subjective, but I personally find MSDN horrible to use, for example).

For the search: Use the Javadoc Search Frame, it makes using Javadoc of all kinds a lot easier. It's available as a Userscript for Firefox and as a Google Chrome Extension.

Answer 4

To answer your Practical Question, I googled and asked friends and came up with these. Forrestdoc,doclet and doxygen.

The second question, I would say that yes, its not very "Web-oh-twoeye" but At least your guaranteed to work in an offline environment, and its small enough to ship along with your API. i dispise the use of frames, but then it works rather well for javadoc. I have not seen any plans to change it. Eclipse has some support for javadoc as far as reading, interpreting and generating it goes.

Answer 5

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.

Answer 6

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.