JDK documentation

[David Holmes - Sun Microsystems]

I don't want to start a meta-debate on these kinds of changes, but I 
feel the need to add a couple more comments :)

Andrew Haley said the following on 11/01/08 12:16 AM:
> Most of the changes I'd make to the javadocs are clarifications, not
> changes in intent.  To clarify, here's an example that bit me.

I understand, but even clarifications are not necessarily 
straight-forward. The point is that someone, or a group of someones, 
will have to evaluate all javadoc changes to establish whether the 
change is truly a "clarification". At the moment all that can be easily 
fixed is true typos and html tagging.

> ... So,
> you can only tell that registerMBean() has this side-effect if you
> read the whole page.

I'm afraid (for better or worse) that this is a style of documentation 
used in many of the JDK libraries. Things that are common across methods 
are often documented once at the class level eg. "Unless otherwise 
stated all methods that take a collection object as an argument with 
throw NullPointerException if the argument is null." And things that are 
common across classes/types are often documented at the package level - 
see the java.util.concurrent package (and sub-package) docs.

There are distinct advantages to writing things correctly once rather 
than repeating them all over and risk missing some cases, and risk 
omitting changes if there is a need for change. The requirement of this 
approach is that the user must read all of the relevant docs ie to 
understand a method you should first have read read the package docs, 
then the class docs, and then the method doc.


Cheers,
David Holmes