# HG changeset patch
# User emcmanus
# Date 1206089380 -3600
# Node ID d436a8afbbd38c38b9f04f93b47a9d42ab1d9652
# Parent  2750e2339c8d0034b80a579ab1a8ec8b9732fdce
6649542: Document explicitly in registerMBean etc that MBeanServerNotification is emitted
Summary: Make spec more readable by adding cross-references.  Suggested by Andrew Haley.
Reviewed-by: dfuchs

diff -r 2750e2339c8d -r d436a8afbbd3 jdk/src/share/classes/javax/management/MBeanServer.java
--- a/jdk/src/share/classes/javax/management/MBeanServer.java	Wed Mar 19 11:13:46 2008 -0700
+++ b/jdk/src/share/classes/javax/management/MBeanServer.java	Fri Mar 21 09:49:40 2008 +0100
@@ -50,7 +50,7 @@
  * server.  A Java object cannot be registered in the MBean server
  * unless it is a JMX compliant MBean.</p>
  *
- * <p>When an MBean is registered or unregistered in the MBean server
+ * <p id="notif">When an MBean is registered or unregistered in the MBean server
  * a {@link javax.management.MBeanServerNotification
  * MBeanServerNotification} Notification is emitted. To register an
  * object as listener to MBeanServerNotifications you should call the
@@ -258,27 +258,43 @@
  */
 public interface MBeanServer extends MBeanServerConnection {
 
-    // doc comment inherited from MBeanServerConnection
+    /**
+     * {@inheritDoc}
+     * <p>If this method successfully creates an MBean, a notification
+     * is sent as described <a href="#notif">above</a>.</p>
+     */
     public ObjectInstance createMBean(String className, ObjectName name)
             throws ReflectionException, InstanceAlreadyExistsException,
                    MBeanRegistrationException, MBeanException,
                    NotCompliantMBeanException;
 
-    // doc comment inherited from MBeanServerConnection
+    /**
+     * {@inheritDoc}
+     * <p>If this method successfully creates an MBean, a notification
+     * is sent as described <a href="#notif">above</a>.</p>
+     */
     public ObjectInstance createMBean(String className, ObjectName name,
                                       ObjectName loaderName)
             throws ReflectionException, InstanceAlreadyExistsException,
                    MBeanRegistrationException, MBeanException,
                    NotCompliantMBeanException, InstanceNotFoundException;
 
-    // doc comment inherited from MBeanServerConnection
+    /**
+     * {@inheritDoc}
+     * <p>If this method successfully creates an MBean, a notification
+     * is sent as described <a href="#notif">above</a>.</p>
+     */
     public ObjectInstance createMBean(String className, ObjectName name,
                                       Object params[], String signature[])
             throws ReflectionException, InstanceAlreadyExistsException,
                    MBeanRegistrationException, MBeanException,
                    NotCompliantMBeanException;
 
-    // doc comment inherited from MBeanServerConnection
+    /**
+     * {@inheritDoc}
+     * <p>If this method successfully creates an MBean, a notification
+     * is sent as described <a href="#notif">above</a>.</p>
+     */
     public ObjectInstance createMBean(String className, ObjectName name,
                                       ObjectName loaderName, Object params[],
                                       String signature[])
@@ -287,12 +303,15 @@
                    NotCompliantMBeanException, InstanceNotFoundException;
 
     /**
-     * Registers a pre-existing object as an MBean with the MBean
+     * <p>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 {@link
      * javax.management.MBeanRegistration MBeanRegistration} interface
      * and returning the name from the {@link
-     * MBeanRegistration#preRegister preRegister} method.
+     * MBeanRegistration#preRegister preRegister} method.</p>
+     *
+     * <p>If this method successfully registers an MBean, a notification
+     * is sent as described <a href="#notif">above</a>.</p>
      *
      * @param object The  MBean to be registered as an MBean.
      * @param name The object name of the MBean. May be null.
@@ -319,7 +338,12 @@
             throws InstanceAlreadyExistsException, MBeanRegistrationException,
                    NotCompliantMBeanException;
 
-    // doc comment inherited from MBeanServerConnection
+    /**
+     * {@inheritDoc}
+     *
+     * <p>If this method successfully unregisters an MBean, a notification
+     * is sent as described <a href="#notif">above</a>.</p>
+     */
     public void unregisterMBean(ObjectName name)
             throws InstanceNotFoundException, MBeanRegistrationException;