Posted by eitan
on May 20, 2004 at 11:43 PM PDT
The recent news article on Pete Freitag launching javadocs.org (see http://today.java.net/pub/n/javadocs.orglaunch ) was of particular interest to me. I must confess, these types of tools strike a chord with me (more on this shortly). It's hard to gauge the general feeling out there in terms of the level of interest in such tools. There seem to be two camps of developers out there. My friend Erik for example has access to all the information he needs directly from within his IDE of choice (IDEA) and never feels the need to resort to javadocs. I on the other hand "grew up" on javadocs, so to speak. And so I resort to them all the time. I can also see javadocs being useful when you don't want to load an API into your IDE and just need a glance at a package, a method listing, or method signature.
Using only my personal javadoc habits as reference, I discovered that while coding, I performed "lookups" all too frequently (it's true though that IDEs have come a long way towards reducing the need for that). The process was aggravating because I'd have to visit a different [local] URL depending on which API I wanted to consult. I quickly got into the habit of setting up my box such that my personal "home page" consisted of a aggregation of links to various APIs. I assume others have done that too. It's always convenient when not on your own box, to reference APIs directly online at java.sun.com. It's also nice to be able to google on a fully-qualified class name and get to the online javadoc page (isn't it nice that google has become a verb).
So, from here, javadocs.org is [imho] the perfect and logical next step. My impression is that this effort is generating interest and that use of javadocs.org will grow. I particularly like the community aspect of such a site. We are, after all, a java community. We share thoughts, often by sharing APIs. I also concur with Pete that this idea is not necessarily unique to javadocs, but could be applied equally effectively to assist us with the myriad of technologies we do battle with each day: css, html, and dozens of other markup languages.
For a long time I've felt the need for a javadoc system that spans APIs. I was fortunate to have acted on this need by developing such a system myself a few years ago. So I took the next step from the powerful but simple mechanism of parsing source code to produce html 3.2 static content: a full-featured web application using an mvc framework, servlets and JSPs, JSTL, a back-end database, and a totally redesigned front-end utilizing CSS and DHTML ad-nauseum, though i'd prefer to say ad-perfection. To support such a system I built a custom doclet to populate my database with the information that javadoc parsed on my behalf.
I use the system daily as I code and am very happy with what I've got. I particularly like the ability to add a feature or change some aspect of the system whenever it suits me. Ok, to be honest, what I like the most is no longer having to look at a monochromatic version of javadocs (I made sure to color-code all programming element types and style all modifiers; javadocs are so much easier to read that way).
I was fortunate to meet and get to know James Duncan Davidson on the excellent "No Fluff, Just Stuff" tours. James helped me come to the excellent decision to open-source my work (intent here is not to try to exploit my position to advertise my work, but I did realize that readers might be curious as to what specifically I'm talking about, so, with apologies, here's the url: http://ashkelon.sourceforge.net/ ). And so I've been able to share the fruits of my labor with others in our community. And it's a great feeling.
After reading this blog entry: http://jroller.com/page/pawnxing/20040512#searchable_javadocs_sweet on an internal Sun effort at something similar to javadocs.org, I was saddened to discover that such nice work was eventually canned.
So, where am I going with this? To Pete Freitag and javadocs.org: this is a great idea! You've done a good thing, a service to our community; thank you! I look forward to discovering how this system will evolve and grow over the coming months and years.