[ACCEPTED]-Are there some good and modern alternatives to Javadoc?-javadoc

Accepted answer
Score: 42

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

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

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

Score: 21

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

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

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

Score: 13

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

Score: 11

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

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

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

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

Score: 5

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

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

Score: 4

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

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

Score: 3

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

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

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

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

Score: 2

There's a DocBook doclet. DocBook is a richer 4 document type than (X)HTML and is better 3 for describing technical content. From 2 DocBook source you can generate all sorts 1 of different output formats.

Score: 2

I personally would like a more readable 18 "comment documentation" standard than the 17 HTML (and hence tag-wieldy) JavaDoc.

For 16 example, MarkDown, as used here, would be 15 excellent, human readable in the source, nicely 14 formatted external to the source.

With the 13 current JavaDoc, I imagine many people use 12 JavaDoc comments, but don't actually document 11 to the extent they could. I'm sure everyone 10 has browsed an API's online JavaDoc that 9 has been non-documented or barely-documented, and 8 thus far harder to use than it should be.

This 7 isn't helped by code-reformatters (e.g., within 6 Eclipse, or maybe upon source commit) that 5 totally destroy any readable structure you 4 might have put within a JavaDoc comment 3 (e.g., a list of items) into one big blob 2 of text, unless you literally use two carriage 1 returns where you wish to use one).

Score: 2

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

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

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

The overall outlook 1 for JDK 7 is pretty grim.

Score: 1

JavaDoc is itself extremely flexible because 19 you can replace the standard doclet with 18 a custom doclet to provide something that 17 meets your projects specific needs.

On the 16 project I've been working on, we created 15 an HTML/XML-based documentation system (using 14 client-side XSLT 2.0 on JS) for our product 13 with JavaDoc fully integrated. For this, a 12 custom doclet was used to produce JavaDoc 11 data in XML, this used tagsoup to ensure 10 even HTML markup within code comments were 9 well formed.

With this, we were able to deliver 8 an interactive user experience using a single-page 7 app (similar to a desktop tool), but all 6 from within the browser - without any server-side 5 code/infrastructure. The viewer included 4 standard features such as search, tree navigation 3 etc.

Here's a link to a sample entry point 2 in the rather vast documentation: JavaDoc viewer sample

Here's 1 an image also: enter image description here

Score: 0

A smart seachable javadoc viewer:

For many times, I face the problem of browsing 12 JavaDoc. I was looking for something just 11 like Adnroid doc search option. At last 10 I get something like that. If you use firefox 9 the solution is here.

  1. Install the plugin 8 GreaseMonkey, its kinda customizing web 7 page the way we see. ( We need to customize 6 any java doc page, so we can search on class 5 name) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

  2. For greasemonkey to work, we need 4 some user script for customization. This 3 can be downloaded by greasemonkey automatically. Install 2 the userscript from JavaDoc search frame or JavaDoc incremental search.

This works great 1 for me.

More Related questions