Kathy Walrath's Blog

Javadoc: How Do We Improve It?

Ten days ago, a survey came out aimed at people who use the automatically generated API documentation for the Java platform. (Many people call this the javadoc, but, strictly speaking, that's just the name of the tool that produces the API doc.) Amy Fowler blogged about the survey back then, but we want still more responses. So, if you haven't already...

Please take the javadoc survey!

It's short. It's sweet. It's your chance to influence the direction of javadoc. Even if you've already given feedback via comments on Amy's blog or mine, please take the survey so your votes can be counted and all the feedback kept in one place.

How can you pass up a chance to answer these questions:

• What source of information (online doc, book, article, forum, etc.) have you found to be the MOST useful for doing Java development?
• Which way do you prefer to view J2SE generated API documentation?
• Which of the following questions would cause you to consult the J2SE generated API documentation FIRST?
• Who's funnier, Stephen Colbert or Jon Stewart?

Maybe that last one's not really on the survey, but the fact that you've read this far means you certainly have the attention span the survey requires. So how about it? Take the survey!

Comments

• Jon Stewart! Colbert is just a copycat/spinoff :)

  Posted by: gfx on February 06, 2006 at 05:15 PM

• Nah...Stewart takes the easy jokes...Colbert's a much cleverer..."The Colbert Report" is outstanding!

  erm...oh yeah...something about java as well...

  Posted by: archangel on February 07, 2006 at 04:38 AM

• How to improve javadoc? USE IT! Look at a typical open source project - how much javadoc coverage do they have? 10%? Less? Javadoc is already very useful, what needs to be done is for people to use it and comment their code.

  Posted by: hexghost on February 07, 2006 at 10:05 AM

• Swing has some seriously laughable javadoc that should be actually written, e.g.:

  getPrototypeDisplayValue

  public Object getPrototypeDisplayValue()

  Returns the "prototypical display" value - an Object used for the calculation of the display height and width.

  Returns:
  the value of the prototypeDisplayValue property
  Since:
  1.4
  See Also:
  setPrototypeDisplayValue(java.lang.Object)

  
  

  Posted by: davetron5000 on February 07, 2006 at 12:17 PM

• Colbert of course, I think all the good writers have left John Stewart's show for Colbert's. And as for any poor javadoc, you're on notice!

  Posted by: abruegl on February 07, 2006 at 01:03 PM

• Stewart because his humor is mainstream and comfortable, like a really nice couch. Colbert is talented, but he's a little wild, rabid at times. He's the bacon to Stewart's cheeseburger.

  With regard to Javadocs, as a beginning programmer they were completely useless. Now that I understand how languages are structured, design patterns, the various important areas, io, networking, gui api structures, etc etc etc, its much more useful.

  However, I still prefer the "Big Three". These represent 3 different ways to learn about Java's features:

  http://javaalmanac.com/egs/? - package-based examples
  http://www.java2s.com/ - function-based examples
  http://jdk.representqueens.com:9090/s/jdk/ - sdk search box

  I only consult the javadocs themselves when i'm searching for a method in a particular place, or really digging into the available methods of a particular class. Having practical/real world examples/snippets is *the* way to learn a language. Didn't we all start our first jobs somewhere by maintaining code?

  Php has an interesting way of dealing with language documentation. They include the comments below which occasionally house example implementations from users:

  http://www.php.net/manual/en/language.oop5.abstract.php

  Not just an api, but also having language features documented along with the api is a great idea. For people learning the concept of programming it's extremely reassuring to only have one place to learn the entirety of it visually at least. The Javadocs themselves definitely are geared towards an able coder with a strong concept of all the various aspects of programming.

  Posted by: ilazarte on February 07, 2006 at 03:19 PM

• well said hexghost. And even if there is a full set of javadoc droves of people don't use it.
  Just look at all the questions popping up in the forums that are easily answered by looking at the list of classes in the API docs for the JDK. Some time ago I got a question from someone who had been told (homework) to do something using a stack. Not only did he have no clue what a stack was (failure of the education system), he didn't know there is a nice stack implementation in Java (failure of the education system maybe), nor had he ever used the API docs (which were installed on his machine I believe).

  Javadoc as it stands is quite good at what it does, provide a set of technical documentation for a set of classes and packages.
  I don't care if people are sometimes frustrated that it can't do more than that without going through hoops, it shouldn't be expected to be useful for other things. Especially people attempting to turn Javadoc into a system for metaprogramming should really go elsewhere.

  Posted by: jwenting on February 08, 2006 at 12:30 AM

• Hi All,

  I have a sort of "love/hate" thing going on with Javadoc.
  Don't get me wrong - Javadoc was a godsend when java came on the scene. However, it hasn't kept up with the paceof web development, and it's design accounts for restrictions that no longer exist.

  Here's an excellent example of what's possible in web based ui's today: ( http://johnvey.com/features/deliciousdirector/demo.html )

  Note that, just like javadoc, the functionality of this site is entirely client-side. Javascript does all the heavy lifting, and xslt + css enable the layout. This is where javadoc needs to go.

  Posted by: nobodyman on February 09, 2006 at 03:15 PM

• I tried taking the survey 3 days ago which gave me an error message

  
  Not Found
  The requested object does not exist on this server

  
  The only email on the page was privacy@..., so I contacted them but haven't heard from them since.

  Anyway, here are my comments:

  First of all: thank god JavaDoc got invented before XML became all-popular. I think right now, it is easy to type, easy to read, well supported by IDEs. In short: It does all the basics exactly right. Building on that foundation, I see a few possible improvements:

  Focus on "concepts": I think of a concept as any idea or construct that comes up in a software system. To understand a system, you need to understand the underlying concepts and how they are related. With JavaDoc, any concept that has been reified as a Java language construct (say, an interface) or that *is* a Java language construct, is easy to document and to reference from other doc comments. Other kinds of concepts currently have to be documented externally and feel disconnected from JavaDoc information (and vice versa). The goal would be that, whereever you are in Java source code, it should be easy to find out about all concepts that are relevant for understanding what is going on at that location.

  Relate concepts: linking the available concepts adds another important layer of information and corresponds nicely to associative human thinking. Some of the semantic web stuff and wikis can serve as inspiration here. JavaDoc already provides the basics (@see) which are well supported by modern IDEs. I'd like to see: back-links ("Who is pointing at me? How?") and @see could branch out into several categories ("more specific", "related", "less specific" etc.).

  Tagging: This is also a kind of relation. Allow concepts to tag other concepts. Even authors could be concepts then and it would be easy to find out about all classes maintained by a certain author.

  Avoid content duplication: @inheritDoc only works for inheritance, I'd like to have a more generic way of including existing content. Note: this need will become less urgent, once one can factor out shared content into (purely abstract) concepts and link to them. The most pressing use case here are overloaded methods.

  Smalltalk-style grouping of methods [1]. Related to tagging.

  Allow for conceptual "zooming": When looking at a package, there are usually a few main classes that constitute the core of the package, while the other classes only have supporting roles. Similar for methods and helper methods [1]. It would be nice if the initial look at a package could be a bird's eye perspective with the option to zoom in on details, should it be necessary. In my own code, I currently use a custom JavaDoc tag to mark the most important classes, link them via @see tags and generate a GraphViz [2] graph of the resulting structure as a kind of poor man's UML.

  PHP allows users to add Wiki-style comments to the public API. I think that would be very useful for Java (if channeled properly).

  
  As another poster mentioned, cookbook-style recipes and howtos provide an important alternate access to an API. I think, they should be factored out into a separate section and be referenced by class comments (as opposed to be included in them). But they definitely should be tightly integrated with "classic" JavaDoc.

  In general, to be truly useful, the chasm between browsing code and documentation must vanish even more. The ideal JavaDoc presenter should be a viewer that dynamically displays various hierarchies, shows source code etc. But maybe that's more the domain of IDEs and the only thing that JavaDoc proper can do is to improve the markup.

  
  Thanks for listening,

  Axel Rauschmayer
  axel (a) rauschma.de

  References:

  Together with a student of mine, I've written a small prototype in Eclipse that helps with lightweight documentation. If you are interested, you can take a gander at: http://www.pst.ifi.lmu.de/Fopra/rauschma/2005/nepper/

  http://www.graphviz.org/

  Posted by: rauschma on February 11, 2006 at 01:29 PM

• Thanks for the feedback, everyone. I asked about a survey outage and nobody knew of one, so hopefully that was just a hiccup. Axel, I've forwarded your message to the e-mail alias where the survey data goes, but it'd still be better if you could take the survey, since the e-mail won't be included in data summaries.

  
  As for Stewart vs. Colbert... Colbert is funnier and his interviews are usually way better. I still watch both shows, though, and I hope Samantha Bee comes back soon.

  Posted by: walrath on February 13, 2006 at 11:16 AM

• I have some doubts that there is some serious check in place when some Sun programmer delivers source code with, or fare to often, without javadoc comments.E.g. how could anyone have accepted "documentation" like the one for all the constants in http://java.sun.com/j2se/1.5.0/docs/api/java/util/zip/ZipFile.html ? (40 undocumented constants in one class).
  Or how comes that on many, many classes and methods the @since tags are missing? Not only on old unchanged classes, but on classes which have been changed recently or in 1.4. Shouldn't it be required from programmers to provide them for each and every method and class? Otherwise a programmers' change to the code base should be rejected.
  Or http://java.sun.com/j2se/1.5.0/docs/api/java/awt/font/TextAttribute.html which is so badly formated that it is hardly readable. Despite the fact that the documentation claims that the class defines "keys and values". While in reality most values are not defined by the class, but given as a barely readable textual definitions.

  I could go on with such examples for a while. The real sad thing is, that this is all in the open for years, but no one cares to fix these things one by one. Instead, you now run a survey. Do you have already formed a committee to process the answers from the survey?

  Posted by: ewin on February 13, 2006 at 02:44 PM

• And please, at the very least, update the default styling. I spend a good time of my life looking at Javadoc. I could do with not looking at a pages that don't look like they were done in 1998.
  

  Posted by: sumitkishore on February 17, 2006 at 09:31 AM

• Nice...
  http://www.impact-fellowship.org/_cusudi/0000007a.htm
  http://www.chaco.gov.ar/meccyt/subsecyt/_act1/0000060b.htm
  http://www.chaco.gov.ar/meccyt/subsecyt/_act1/00000353.htm
  http://www.wapug.org.uk/_CoP_discussion/00001ca9.htm
  Harvard - Harvard

  http://www.wapug.org.uk/_CoP_discussion/00001ca8.htm
  Stanford - Stanford
  http://washington.uwc.edu/about/faculty/rybak_c/webpage/_disc10/00005663.htm
  http://orgs.salisbury.edu/fishing/Discussion/0000737f.htm
  Yale - Yale

  Posted by: jamesdalton on January 21, 2008 at 12:40 AM

• rgr gfhgfh ghf hgh dgh dh Buy Viagra online
  Buy Viagra Soft Tabs

  Posted by: asder on May 21, 2008 at 10:50 PM

This work is licensed under a Creative Commons License.