JDK documentation

[Andrew Haley]

David Holmes - Sun Microsystems writes:
 > 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".

Sure, but that's surely no different from any other change to the
source code.  Write a patch, submit, get it approved.

 > 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.

Of course, but that doesn't mean that in this case someone could not
add an informative note along the lines of

  INFORMATIVE: This method has the side-effect of emitting a
  MBeanServerNotification Notification; see the XXXX para above.

This note is clearly not normative so it doesn't change the spec, but
it does make life much easier for the reader.  How would it hurt?

Getting such a change approved should not be difficult, given
reasonable patch approval processes.  It's surely not necessary to get
committee approval for every such change.

Andrew.

-- 
Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SL4 1TE, UK
Registered in England and Wales No. 3798903