JDK documentation

[Andrew Haley]

David Holmes - Sun Microsystems writes:

 > Thanks for clarifying that it was the guides you meant - I totally
 > agree they should be opened up and expanded/improved by the
 > community.
 > 
 > But I disagree with what you say about the javadocs. While the
 > javadoc are part of the source files, they form the specification
 > for the platform API's and as far as I am aware the specification
 > for the Java platform is not open-sourced. So any "fixes" to the
 > javadocs would not, I believe, be acceptable through OpenJDK
 > contributions, unless done as part of a JSR. Hopefully Mark, or
 > someone else in the know, could clarify this.
 > 
 > I know I've been frustrated over the years by the apparent
 > inability to get anything but the most trivial typos fixed in the
 > docs, except during major releases. It would be nice if that could
 > change but I'm not aware that it has at this stage.

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.

The javadoc for javax.management.MBeanServer.registerMBean() says, in
full, "Registers a pre-existing object as an MBean with the MBean
server. If the object name given is null, the MBean must provide its
own name by implementing the MBeanRegistration interface and returning
the name from the preRegister method."  The overview at the top of the
page also says "When an MBean is registered or unregistered in the
MBean server a MBeanServerNotification Notification is emitted."  So,
you can only tell that registerMBean() has this side-effect if you
read the whole page.

I would change that method's decription to something like "Registers a
pre-existing object as an MBean with the MBean server, emitting a
MBeanServerNotification Notification.  If the object name given is
null, ...."

This is not a specification change, but makes it easier to understand
the javadoc.

Andrew.

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