Ben Galbraith's Blog

Finally... Interactive JavaDocs

Over the past few weeks, I've watched with anticipation as Rick Ross and Matt Schmidt from Javalobby have put together jdocs.com, an on-line JavaDoc search engine. As the site has matured in recent days, I've enjoyed using it in place of my downloaded JavaDocs.

(Note that jdocs.com is built on the open-source project Ashkelon, a powerful JavaDoc indexing tool -- much more than a search engine bolted onto JavaDocs -- created by java.net's own Eitan Suez. I was treated to a demo of Ashkelon by Eitan several weeks ago and was very impressed, although saddened that the project is so little known.)

The killer feature of jdocs.com is the ability for developers to comment on individual JavaDoc entries. Having used this functionality on other sites to great positive effect before, I can't wait to start leaving comments of my own -- if nothing else for my own future use.

As other like-minded developers start leaving their own comments, jdocs.com may become a virtual hivemind of Java knowledge (apologies to my friend Howard), helping newbies discover, for example, that calling setLocationRelativeTo(null) is how you center a Window in AWT/Swing, or that you need to use a Transformer to save a DOM tree (ah, that intuitive W3C DOM API...).

Hopefully, as the site matures, comments will span versions of an API and the comments of superclasses will be visible in some natural way in the API of subclasses (or at least acknowledge their presence).

Some may view the on-line ads injected into the JavaDocs as a nuisance. I'm actually quite intrigued by the possibilities; this could evolve into an ideal platform for component vendors to hawk their wares, and for developers to more fully understand their options. Imagine querying the JavaDoc for JTree and seeing an ad for an alternative GUI tree component or any number of other similar scenarios.

I've already integrated jdocs.com with my IntelliJ IDEA projects and use it for my JavaDoc queries. Congratulations to Rick and Matt for one of the most exciting new community resources in a long time -- and keep the innovation coming!

P.S. The Javalobby folks aren't quite sure how much load the site's going to be under as the word gets out, so be kind over the next few days as they ramp it up.

Comments

• Classfinder
  Just remembered - you can drop in multiple versions of an API (e.g. J2SE 1.3 /1.4 / 1.5) and switch versions at will.

  Anyway, that's enough of my advocacy...!

  Posted by: brianagnew on August 10, 2004 at 04:25 AM

• Classfinder
  The best solution I've found for Javadocs is Classfinder.

  Simply run it locally, drop your Javadoc jars into its repository directory, and it dynamically ties all your docs into one Javadoc repository, with search capabilites.

  You don't need a servlet engine, a database etc.

  If you have the source .jars, it'll tie those into the doc as well, so you can swap between doc and code at will.

  Posted by: brianagnew on August 10, 2004 at 11:12 AM

• Classfinder

  Looks interesting. I find the most interesting part of jdocs.com to be (a) its comments feature and (b) being able to use it from any of my (many) development machines and from client sites. Therefore, a local JavaDoc website doesn't excite me as much.

  
  But if I were to run a local JavaDocs repository, I'd probably use Ashkelon -- it's really very cool.
  

  Posted by: javaben on August 10, 2004 at 11:17 AM

• thanks for the heads up!
  Looks very useful.

  I'd like to see the ability to extend this with some sort of Wiki functionality so the user added comments can be put to more use, but it looks like a great start.

  Posted by: refux on August 10, 2004 at 01:03 PM

• I hate to sound stupid...
  How does one use JDocs.com with IDEA? I would love to take advantage of JDocs with my projects at work.

  Thanks,
  Dave

  Posted by: vesperdem on August 10, 2004 at 10:41 PM

• I hate to sound stupid...
  I truly never noticed that "Specify URL..." button. Thanks!

  I hope it doesn't take long to start filling up, the interactive documentation on www.php.net has helped me out pleanty of times. I'm sure these interactive JavaDocs are going to help me out just as much if not more!

  Posted by: vesperdem on August 11, 2004 at 04:53 AM

• I hate to sound stupid...
  When you setup any library or JDK in IntelliJ IDEA, you can specify either a directory or a URL for the JavaDocs. Go ahead and specify the base URL for the JavaDoc you want on jdocs.com in IDEA and it'll work.

  Posted by: javaben on August 11, 2004 at 06:46 AM

• Annotating
  Regrettably, there's no annotations at all to provide a preview.

  Posted by: sumitkishore on August 11, 2004 at 12:23 PM

• Annotating
  Here's one:

  MouseEvent.getClickCount()

  Perhaps a "latest n comments" feature would be useful...

  Posted by: javaben on August 11, 2004 at 12:27 PM

• List of recent comments
  We have a tag to show the recent comments, we just haven't put it up on the frontpage yet. So that there's something to tide you over, browse over to http://www.javalobby.org/forumcategory.jspa?categoryID=42

  You should see the recent posts there at the bottom.

  -Matt

  Posted by: mpschmid on August 11, 2004 at 12:30 PM

This work is licensed under a Creative Commons License.