Joshua Marinacci's Blog

Posse Brain Dump: JavaDocs from the year 2020

At the Java Posse Roundup last week we had some wonderful evening sessions called Lighting Talks. During these sessions each participant had 5 minutes to give their entire presentation. This necessitates, of course, brevity and clarity above all. And of course, since this was the evening, we were all sitting around munching on BBQ, drinking beer, and laughing away during the proceedings. So in short, it was a lot of fun. Some of the talks were Java related at all. Ido Green from Yahoo introduced us to the sport of orienteering and Joe Nuxoll from the Java Posse gave several presentations about the physics of race car driving. Fascinating stuff.

Anyway, back to what I came to talk about. What I'm about to show you is several demos that have been sitting on my harddrive for a while. I pulled them out and showed them to the Roundup attendees with a warm reception. This convinced me that some of you might like to see them too.

I want to state at this point that these are not SwingLabs projects. They are simply demos to try out ideas. However they all have the potential to be great SwingLabs projects. If you think they would be a good project and would like to help run it then please email me and Rich so we can get you started. Thanks.

No on with the show! I'll send out a different blog with each of these. Here's the first:

JavaDocs from the year 2020

This was an experiment in what we could do with Javadocs now that most browsers support Javascript and CSS very well. The code is pretty simple: a custom doclet which produces XML, then run through XSLTs to produce HTML which uses custom CSS and Javascript. All as spec compliant and clean as possible. The design of the new interface is both prettier and more functional than standard javadocs. It shows off lots of interest ideas like:

click to view live

• organizing docs by category using tabs
• grouping properties into a single unit
• conditionally hiding advanced and deprecated methods
• collapsing inherited methods into open/close strips
• pinning common features to a fixed header at the top
• reducing the vertical space used to show more docs at once.
• better styles for the overview and code snippets
• rollover/tooltips to show the full classname

Note that I've only done the classes themselves, not the class list or package level docs, so that's very spare right now.

Let me know what you think. More coming soon.

- Josh

Comments

• Hi, Josh; one thing that I've been meaning to write for ages and never have the time for is some sort of (even primitive) support for tagging and javadocs. Frequently I want to tag various classes as belonging to thus-and-such a layer, or being implementation-based versus contractual. You can do something crudely similar to this at a package level in javadocs today, but it would be great if a doclet or javadoc reimagining such as this one would adopt some of those awfully-named "web 2.0" features to help comprehension of a codebase.

  Posted by: ljnelson on March 14, 2007 at 01:38 PM

• Please make the frameset go all the way away.

  An optional ".war" output for interactive/searchable docs would also be nice. In addition to JNLP browsing of the XHTML JavaDoc output and/or web services. Note that the JNLP app wouldn't just be a web browser, but rather dig metadata exposed in the documents/services.

  For tagging (if support is wanted), just surface easy browsing by @Annotations that follow certain conventions. Or stick to old-fashioned tag interfaces.
  

  Posted by: tompalmer on March 14, 2007 at 02:14 PM

• Why not dump everything to a database and write a Swing based browser? Is there something about this nail that makes Swing the wrong hammer?

  Posted by: coxcu on March 14, 2007 at 04:14 PM

• hmm..to me this sounds more like javadocs from the year 2002. this is what i implemented in ashkelon approximately five-six years ago. i still use the system daily though i never did the work to update the system when java 5 came out.
  see http://ashkelon.sourceforge.net/screenshots/string-brief.png

  Posted by: eitan on March 14, 2007 at 04:39 PM

• I have to agree with coxcu. I think it's probably reasonable to assume Java developers will have Java on their machine. Having said that, I run a 64-bit OS, so don't have a native WebStart. How shameful is that?

  I think the real problem with a proper application to show the docs is that they always descend into usability hell (perhaps not so different to HTML + increasingly complex JavaScript). Look at NetBeans - it's painful to use.

  Posted by: tackline on March 14, 2007 at 05:30 PM

• These all sound like great suggestions, and now that Java is open source I encourage you all to try to implement them. My version of the Javadocs was an attempt to start a conversation and come up with something better than what we've been using for the last ten years. You all have some great ideas. I'd love to see them in action.

  Posted by: joshy on March 14, 2007 at 09:58 PM

• Great minds think alike! I've been having a go at the same idea, outputting javadocs to XML and then using XSL to render in a browser, with a view to doing a web-start Swing container later. However my output is rather different - I'll try and get an example uploaded later on. Meanwhile, I've been blogging about this for a few weeks. You'll have to read from the bottom up, though, due to LJ's limited tagging facilities.

  Posted by: peeet on March 15, 2007 at 06:45 AM

• Very nice! Yes. I think this would make a great Swinglabs project.

  Posted by: evickroy on March 15, 2007 at 08:27 AM

• Is this related to JSR 260 at all?

  Posted by: alexdmiller on March 15, 2007 at 11:11 AM

• Further to my comment above, there's a link to an example of my custom doclet's output on my latest post.

  Posted by: peeet on March 15, 2007 at 12:08 PM

• alexdmiller No, this isn't related to JSR 260, but I think it should be. If we are going to redesign Javadocs then we should start by thinking about what the end product will be.

  Posted by: joshy on March 15, 2007 at 12:49 PM

• Nice...
  Of course Frames will have been banned in all civilized countries by 2020.
  And by 2020 we can make it more interactive.. think of mixing it with this:
  http://jdk.representqueens.com:9090/s/jdk/
  and a wiki, junit/fitnesse.. yada yada
  

  Posted by: firefight on March 15, 2007 at 02:42 PM

• Why not dump everything to a database and write a Swing based browser? Is there something about this nail that makes Swing the wrong hammer?

  Because of the VM startup time. I have a browser or a new browser window up in no time, and probably have seen what I want to see while the VM is still burning CPU cycles and I/O bandwidth like there is no tomorrow just to get going.

  I use a browser when I need to look up something quickly and don't have an IDE running. If I would like to wait I could start the IDE.

  And while modern browser are memory hungry, they are not as hungry as a VM. And while browsers might need a seconds to load a file and render it, they are still much faster than a Java program opening a database connection, querying the DB and then rendering some result.

  Which leads to the next issues: Java2D's poor rendering capabilities, e.g. the mediocre quality of the font rendering, the abysmal rendering of attributed text (while consuming a lot of memory for the internal representation). You should also keep in mind that there is usually a vast difference between the bling-bling Sun likes to demo and the low quality of GUIs in the products Sun actually delivers.

  So in the end you get an API documentation system which is much slower than a web browser, but with twice as ugly contents. But hey, it would be written in Java.
  

  Posted by: ewin on March 15, 2007 at 02:43 PM

• I think JVM startup time is a non issue when talking about browsers, because on the machine at work IE 7 takes 3-8 seconds to start anyway. 8 seconds if I haven't started it for a while, then if I close it and open it again immediately, 3 seconds.

  Opera has a similar startup time.

  So with the work that has gone into speeding up the JVM startup, I think the gap will have closed significantly. Heck, by 2020 the whole operating system might run on Java (and: tossing a bone to the _other_ Joe... be written in Scala).

  Posted by: rickcarson on March 15, 2007 at 03:32 PM

• Color scheme is ugly and UI looks terrible!. You must be kidding about the year 2020 Josh!
  Sorry guys, but I've to inform you that the Wunderkind has no Clothes!!!
  Ogun

  Posted by: otigli on March 16, 2007 at 01:45 AM

• I like the look, I take it you're also hiding the getter/setter methods behind the properties sheet. Hiding the full package name and the inherited methods might rub me up the wrong way. Quite often I'll select and copy the full package name from javadocs directly into my code and I'm often traversing up a class hierarchy to find where things are implemented esp. with spring mvc controllers. Dislike the idea of needing to expand the inherited section each time to keep traversing upwards. Maybe I just need a 'implemented by' option in the first place.

  One thing that struck me is how do we document annotations related to any given class/package.

  It's not too hard to improve the look of something developed ten years ago. Just using a nice sans serif font that works better with cleartype (Windows) would be a big help. Can't much of this be achieved already with work to the doclets or greasemonkey magic.
  

  Posted by: osbald on March 16, 2007 at 04:07 AM

• I'm not a graphic designer so of course it could use a visual makeover. I just wanted to show something so completely different than standard JavaDocs that people would take notice.

  The full package name is hidden but you'll see it in a popup when you mouse over the class and method names. I agree about the inherited section being collapsed. Really this is just an expansion on how we do things now. Currently you just get one big long list of method names that are inherited. You don't even get the method arguments so JComponent has about 4 different add methods which are indistingushible! Really, we should show the full javadocs up front not of methods that are overridden or declared in this class, but insteads show the full javadocs of the methods that are important. For example. JButton gets most of it's useful stuff from AbstractButton, so those methods like isSelected() should show up locally. They are more important than merely being inherited. paint() on the other hand should never be used and should be hidden completely. Really we need annotations of some sort to indicate what's important and what isn't. Something to say: "make sure this doc is propagated up to all subclasses".

  We also need a way to show annotations. The Doclet API gives me access to them, I just haven't built support for it yet.

  a lot of what I've done here could be accomplished by simply replacing or upgrading the standard doclet. Some things involve a spec change however. We need a way to indicate which methods are advanced and to specify categories. That's something I hope the JavaDoc JSR will address. Properties really should be specified with a doc tag too.

  Posted by: joshy on March 16, 2007 at 07:39 AM

• I agree with other and I do a question:
  Why don't turn the javadoc into something alike with the shown or maybe better taking the given suggestions or others suggestions and after that put the new doclet in JDK7?
  

  Posted by: edwardboszczowski on March 17, 2007 at 02:01 PM

• Hi Josh.

  Are you planning on making available the XSLTs? I toyed around with the html adding support for Google Code Prettify (http://code.google.com/p/google-code-prettify/) and the results look pretty cool (no pun intended. really.).

  Posted by: rafaeldff on March 25, 2007 at 09:24 PM

• Sure. I'll provide a code dump to whoever wants it. The code prettifier sounds neat. Could you upload a screenshot somewhere?
  

  Posted by: joshy on March 26, 2007 at 09:52 AM

• Here is the screenshot.

  Posted by: rafaeldff on March 26, 2007 at 02:34 PM

• Wow. That looks pretty sweet. It sounds like we could really use a new javadoc tool that did these kinds of effects.

  Posted by: joshy on March 27, 2007 at 09:12 AM

This work is licensed under a Creative Commons License.