JDK documentation

[Eamonn McManus]

Andrew,

I realize that this doesn't address the more general problem being 
discussed here, but we can at least fix the JMX documentation in version 
2.0 of the API, which is currently targeted for JDK 7. I've logged RFE 
6649542 to track this.

Regards,

Éamonn McManus   JMX Spec Lead   http://weblogs.java.net/blog/emcmanus/



Andrew Haley wrote:
> 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.
>
>