Let's face it: You don't need to be a designer to see that default Javadoc looks ugly .
There are some resources on the web which offer re-styled Javadoc. But the default behaviour represents the product and should be as reasonably good-looking.
Another problem is the fact that the usability of Javadoc is not up-to-date compared to other similar resources.
Especially huge projects are hard to navigate using Firefox's quick search.
Practical question:
Are there any standalone (desktop) applications which are able to browse existing Javadoc in a more usable way than a browser would?
I'm thinking about something like Mono's documentation browser.
Theoretical question:
Does anyone know, if there some plans to evolve Javadoc, in a somehow-standardized way?
EDIT: A useful link to Sun' wiki on this topic .
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).
ReplyDeleteNevertheless 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.
I have created a Markdown (java) Doclet which will take source comments in Markdown formatted text and create the same HTML Javadocs.
ReplyDeleteThe 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.
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.
ReplyDeleteI recently got a mail forwarded that Sun is working on modernizing the Javadoc HTML output. From said mail:
ReplyDeleteWe 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.
To answer your Practical Question, I googled and asked friends and came up with these. Forrestdoc,doclet and doxygen.
ReplyDeleteThe 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.
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).
ReplyDeleteFor 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.
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.
ReplyDeleteAnd 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.
There's a DocBook doclet. DocBook is a richer document type than (X)HTML and is better for describing technical content. From DocBook source you can generate all sorts of different output formats.
ReplyDeleteI personally would like a more readable "comment documentation" standard than the HTML (and hence tag-wieldy) JavaDoc.
ReplyDeleteFor example, MarkDown, as used here, would be excellent, human readable in the source, nicely formatted external to the source.
With the current JavaDoc, I imagine many people use JavaDoc comments, but don't actually document to the extent they could. I'm sure everyone has browsed an API's online JavaDoc that has been non-documented or barely-documented, and thus far harder to use than it should be.
This isn't helped by code-reformatters (e.g., within Eclipse, or maybe upon source commit) that totally destroy any readable structure you might have put within a JavaDoc comment (e.g., a list of items) into one big blob of text, unless you literally use two carriage returns where you wish to use one).
Does anyone know, if there some plans to evolve Javadoc, in a somehow-standardized way?
ReplyDeleteThe 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.
Since long ago we offer a tool called DocFlex/Javadoc (or DocFlex/Doclet, a simplified version of it).
ReplyDeleteBasically, this is a template-driven Javadoc doclet.
That may sound like nothing remarkable (everything has now some kind of "templates"). But our templates are different. They are actually programs somewhat similar to XSLT. But this is not XSLT either. Our templates are created with a special graphical Template Designer, which tries to represent them in a way resembling the output they will generate (i.e. the WISIWIG of a sort).
The idea of the whole our technology is to represent any Java API as a virtual XML document and process that "document" using techniques borrowed from the field of XML like XPath (or some extension of it). There are many other innovations. More details you can find here: "http://www.filigris.com/products/docflex/"
You can use DocFlex/Javadoc to program your own doclets. It is not limited to any specific pattern. Any kind of documentation design, look & feel can be programmed to generate with it. We support currently two major output formats HTML (both framed and single file) and RTF, plus the plain text output.
DocFlex/Javadoc is supplied with a default template set that produces JavaDoc similar to the standard one. Very soon we are releasing a new version of it that will generate the output documentation absolutely identical to the standard Javadoc (with the same navigation bar, menu items etc).
One plus of our template-driven implementation is that unlike standard Javadoc, it allows you to include/exclude classes and member marked with specific tags or annotations. At that the generated JavaDoc will be consistent after that. That a rather by-product feature was quite simple to implement basing on the already existed general functionality. Surprisingly, it happened to be very much in demand (more than the whole thing itself).
The entire our technology, in fact, is not limited to Javadoc. The main direction is currently about XML (see DocFlex/XML: "http://www.filigris.com/products/docflex_xml/"). For instance, we offer now a very powerful XML Schema Documentation Generator (see "http://www.filigris.com/products/docflex_xml/xsddoc/", probably the most sophisticated in the world. A similar documentation generator for WSDL is also in the pipeline.
DocFlex/Javadoc is somewhat a by-product of all this, albeit the most beautiful one.
A smart seachable javadoc viewer:
ReplyDeleteFor many times, I face the problem of browsing JavaDoc. I was looking for something just like Adnroid doc search option. At last I get something like that. If you use firefox the solution is here.
Install the plugin GreaseMonkey, its kinda customizing web page the way we see. ( We need to customize any java doc page, so we can search on class name)
https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/
For greasemonkey to work, we need some user script for customization. This can be downloaded by greasemonkey automatically. Install the userscript from JavaDoc search frame or JavaDoc incremental search.
This works great for me.