Tim Boudreau is a noted technology consultant, evangelist and author. While perhaps most broadly known for his leadership on Sun Microsystems’ NetBeans, those who’ve worked with Tim remark most on his technical chops, passion for a great challenge and rare gift of great communication. And, as a former troubadour, he’s pretty tough when it comes to bad 70s rock lyrics too. A real renaissance programmer. Tim has posted 25 posts at DZone. You can read more from them at their website. View Full User Profile

How Not to Write Java Documentation...

02.10.2009
| 14247 views |
  • submit to reddit
I've got this draft box full of unpublished blogs - mostly because they might insult somebody. This one is five years old and as apropos today as it was then.

2005-07-25 00:48:52 A java newbie posted to nbusers saying "I want to put an image into an AWT frame. What component do I use?"

Strangely, the answer is, there isn't any. It's trivial to write one:

public class ImagePanel extends Canvas {
private BufferedImage img = null;
public ImagePanel(String name) {
setImage (name);
}

/** Load an image from the jar, path relative to ImagePanel.class */
public void setImage (String name) throws IOException {
img = ImageIO.read(ImagePanel.class.getResourceAsStream(name));
}

public Dimension getPreferredSize() {
return img == null ? new Dimension() : new Dimension (img.getWidth(),
img.getHeight());
}

public void paint (Graphics g) {
if (img != null) {
((Graphics2D) g).drawRenderedImage(img,
AffineTransform.getTranslateInstance(0,0));
}
}
}

Before someone cries "Ha! Gotcha! You Sun employees are dummies!", yes, there is a blazingly, stunningly non-obvious way to do this in one line of code:

new JLabel (new ImageIcon (ImagePanel.class.getResource("some_jpeg.jpg")))
No newbie is ever going to figure that out. It's compact and cute. But it doesn't count. Too non-obvious.

The thing is, I can totally imagine this guy's situation. I want to display an image. Seems simple enough - there ought to be a component for that. But there isn't any obvious candidate. Putting myself in his shoes (screen goes fuzzy as we flash back to my first days coding in Java)...

So I look at the docs for java.awt.Image. It says "The abstract class Image is the superclass of all classes that represent graphical images. The image must be obtained in a platform-specific manner." Well, that's not too useful... [not to mention wrong - or at least, misleading - ImageIO.read() is pretty platform independent, and so is Toolkit.loadImage()]. Hmm, I'll try the docs for BufferedImage, it's a subclass. Hey, that's better. It says "The BufferedImage subclass describes an Image with an accessible buffer of image data. A BufferedImage is comprised of a ColorModel and a Raster of image data." Hmm, nothing about reading or loading an image here. Where do I get one? I'll try Raster, that's its data, maybe that's where you load the data...

At this point I've gone down the rabbit hole - I'll spend at least a half hour digging through Rasters, ColorModels, ImageObservers and all sorts of other bric-a-brac that's useful if you're writing HotJava or Photoshop - when all I want to do is get my grubby little paws on an image!

There is a school of thought that says reference documentation should only describe the topic being discussed - and I disagree violently with it. This is a perfect example of why - someone is trying to do a very simple task - display an image. They have components. Fine. They have images. Fine. But nowhere in the documentation does it say either how to get an instance of an image, or how to paint one once you've got it!

I'm just amazed. The code above is very simple, but one could easily spend a day trying to figure out what to do and end up with something massively more complex. How many hours have how many people wasted over the years, starting out in Java, just trying to do this simple thing and running into this particular brick wall?

So, please, for all that's precious in the world: If you're writing javadoc for a class and it's not incredibly obvious how to get an instance of that class, describe where you get one. Describe the basic steps of how to use it. Especially if the thing someone does with it is not expressed in methods on it. If a documentation style maven says your docs are cluttered, tell them I told you they should be cluttered. If someone very clever comes along and says (ominous soundtrack), "Ah, but you're going to have to maintain that documentation. You say, okay, I'll maintain it. And if your documentation maven then says, "What if one day your example is WRONG!!!" pat him on the head, tell him he's very clever (that's all he wants anyway) - and send him on his way.

Reference documentation may be intended to be "reference" documentation - i.e. it talks about the thing the documentation refers to. That doesn't mean it should talk about nothing else, like how to use the thing being referred to.

From http://weblogs.java.net/blog/timboudreau/

Published at DZone with permission of its author, Tim Boudreau.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Franz Wong replied on Tue, 2009/02/10 - 3:46am

I always get bad feeling with Java documentation.

I am not going to compare Microsoft and Sun. For documentation in MSDN, there are summary pages for each class. Usually, sample code is given on that page (Image class (.NET)). I am quite appreciate of it.

Back to Java. Suppose I don't know how to read a image file. After some googling, I find a page teaching how to load an image. It is a tutorial page (Reading/Loading an Image) from Sun. But you can't find a link pointing to this page inside Java API Documentation.

After reading that tutorial, I know I should use "ImageIO" class to read the image file. Fine.

If I didn't read that tutorial page, I must need some time to find out the appropriate method on this page (ImageIO (Java)).

Geertjan Wielenga replied on Tue, 2009/02/10 - 4:10am

Good point. The Java tutorials are there. The Javadoc is there. Why not connect them?

In NetBeans we're trying to do exactly that.

Jeroen Wenting replied on Tue, 2009/02/10 - 4:39am

See my response to your identical post on java.net.

Christian Beer replied on Tue, 2009/02/10 - 4:52am

I wonder why you first talk about a problem with AWT and then show a Swing 1-line solution?

But I also wondered why there was no image component. I never understood why you take a JLabel to show an image. It should have been split up in JImageView and JLabel.

Ronald Miura replied on Tue, 2009/02/10 - 6:48am

Not only the documentation is broken, the APIs (both AWT's and Swing's) are not really appropriate for today's uses (maybe it was different back then, when the equivalent in C++ was even more cryptic).

Maxim Zakharenkov replied on Tue, 2009/02/10 - 6:54am

I think that the demonstrated example is not about the documentation. May be documentation could help somehow, but I suppose that if Swing/AWT had a component ImagePanel or something like this. All the questions would be answered. I'm not sure about everybody, but when I first look at any GUI toolkit and I need an image to display I first look for a component like "Image, ImagePanel, Bitmap etc", but not JLabel! And also I expect that this component will have a String parameter which is an image name. In this case need a very minimal documentation.

Look also at Flash documentation here: Bitmap

It's taken a few seconds for me to find the right class. I've just guessed it by package name and class name. And even more, they have also a perfect code example on how to use it!

 

 

Matteo Gallinucci replied on Tue, 2009/02/10 - 9:02am

I think you are right, often you do a random search in documentation trying to find the right class to use. Like deprecated methods tell you what you should use now instead, documentation should be complete, linking tutorials or putting some short examples.

Personally I like ExtJS documentation, where there are some examples and links between related classes.

Eric Anderton replied on Tue, 2009/02/10 - 10:24am

"There is a school of thought that says reference documentation should only describe the topic being discussed - and I disagree violently with it."

Great Article - I think we've all been here, especially with the JDK.

Perhaps it's an indication that something is very wrong with Java's documentation, but this is why we have the phone-book sized Java Almanac, that is organized categorically by task.  More to the point: it's impossible to write a decent application the first time out without a copy, and harder still if you don't know it exists.

Francois Marot replied on Tue, 2009/02/10 - 10:46am

Yeah, we've all been there... The lesson I learn is always, yes ALWAYS teach newbies about the java tutorial, and most notably its "big index": http://java.sun.com/docs/books/tutorial/reallybigindex.html

This is THE most complete tutorial about nearly every aspect of Java and it answers nearly all basic needs. In Java, it seems the Javadoc documents the classes themselves. If you want to know which class to use when, refer to the Java tutorial. It's not so bad after all. But the problem is that not everybody knows of this tutorial. Even Java programers in business for some years are unaware of this fundamental resource. I think that's the biggest problem.

Guido Amabili replied on Tue, 2009/02/10 - 11:29am

 

What I have missed the most in the javadocs (xml parsers for example) is 2-3 lines of sample code . But I feel this is improving with the latest projects I have seen (or is it my java understanding ?)

Maybe there could be something like @example tag  ?

GuidoLx

 

 

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.