Javadoc: What a Joke

The idea of javadocs have always been pretty cool: a standardized way to document code and then view that documentation. Sun did a pretty good job enabling Java code to be documented in a consistent way.

What Sun didn't do a good job of was producing a useful javadoc tool. The javadoc binary has always been a pretty crappy tool, and today it has shown itself to be useless. The fact that every single class/package had to be listed on the command line in order to be "javadoc'd" made absolutely no sense. Nobody javadocs one file at a time, people javadoc entire projects all at once. Multiple packages, hundreds of files. This is the norm. Yet through over a decade of Java development Sun apparently still has no idea that this is how real Java developers write and document code (maybe this is why they come up with such poor technology specs? Do I need to mention EJB's? JPA is starting to look like garbage, too, a real step BACKWARDS from Hibernate.)

And today, I tried to fun javadoc on my entire project, passing in every single Java file since Javadoc insists on that, and I got this:

Building index for all the packages and classes...
Generating html/overview-tree.html...
Generating html/index-all.html...
java.lang.ClassCastException: com.sun.tools.javadoc.ClassDocImpl

Are you kidding me?! Is this for real?? A ClassCastException?? Who puts out production code like this? This is on JDK 1.5_06. Absolutely ridiculous.