8022406: Fix doclint issues in java.beans

Reviewed-by: prr

src/share/classes/java/beans/AppletInitializer.java

 /*
- * Copyright (c) 1997, 2000, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -68,7 +68,6 @@ public interface AppletInitializer {
      * the Applet with its Container during the subsequent invocation of its
      * addChildren() method.
      * </ol>
-     * </p>
      *
      * @param newAppletBean  The newly instantiated JavaBean
      * @param bCtxt          The BeanContext intended for this Applet, or

src/share/classes/java/beans/Beans.java

 /*
- * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -62,7 +62,7 @@ public class Beans {
      * <p>
      * Instantiate a JavaBean.
      * </p>
-     *
+     * @return a JavaBean
      * @param     cls         the class-loader from which we should create
      *                        the bean.  If this is null, then the system
      *                        class-loader is used.
@@ -82,6 +82,7 @@ public class Beans {
      * <p>
      * Instantiate a JavaBean.
      * </p>
+     * @return a JavaBean
      *
      * @param     cls         the class-loader from which we should create
      *                        the bean.  If this is null, then the system
@@ -137,6 +138,7 @@ public class Beans {
      * the JDK appletviewer (for a reference browser environment) and the
      * BDK BeanBox (for a reference bean container).
      *
+     * @return a JavaBean
      * @param     cls         the class-loader from which we should create
      *                        the bean.  If this is null, then the system
      *                        class-loader is used.
@@ -361,6 +363,8 @@ public class Beans {
      * This method is provided in Beans 1.0 as a hook to allow the
      * addition of more flexible bean behaviour in the future.
      *
+     * @return an object representing a specified type view of the
+     * source object
      * @param bean        Object from which we want to obtain a view.
      * @param targetType  The type of view we'd like to get.
      *
@@ -384,7 +388,6 @@ public class Beans {
         return Introspector.isSubclass(bean.getClass(), targetType);
     }
 
-
     /**
      * Test if we are in design-mode.
      *

src/share/classes/java/beans/ConstructorProperties.java

 /*
- * Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -61,7 +61,7 @@ import static java.lang.annotation.RetentionPolicy.*;
    the {@code getY()} method.  Since parameter names are not in
    general available at runtime, without the annotation there would be
    no way to know whether the parameters correspond to {@code getX()}
-   and {@code getY()} or the other way around.</p>
+   and {@code getY()} or the other way around.
 
    @since 1.6
 */

src/share/classes/java/beans/DefaultPersistenceDelegate.java

 /*
- * Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -382,6 +382,7 @@ public class DefaultPersistenceDelegate extends PersistenceDelegate {
      * a class such that no property value depends on the value of
      * a subsequent property.
      *
+     * @param type the type of the instances
      * @param oldInstance The instance to be copied.
      * @param newInstance The instance that is to be modified.
      * @param out The stream to which any initialization statements should be written.

src/share/classes/java/beans/EventHandler.java

 /*
- * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -515,6 +515,7 @@ public class EventHandler implements InvocationHandler {
      *</pre>
      *</blockquote>
      *
+     * @param <T> the type to create
      * @param listenerInterface the listener interface to create a proxy for
      * @param target the object that will perform the action
      * @param action the name of a (possibly qualified) property or method on
@@ -570,6 +571,7 @@ public class EventHandler implements InvocationHandler {
      *</pre>
      *</blockquote>
      *
+     * @param <T> the type to create
      * @param listenerInterface the listener interface to create a proxy for
      * @param target the object that will perform the action
      * @param action the name of a (possibly qualified) property or method on
@@ -659,6 +661,7 @@ public class EventHandler implements InvocationHandler {
      * </pre>
      *</blockquote>
      *
+     * @param <T> the type to create
      * @param listenerInterface the listener interface to create a proxy for
      * @param target the object that will perform the action
      * @param action the name of a (possibly qualified) property or method on

src/share/classes/java/beans/Expression.java

 /*
- * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -139,7 +139,7 @@ public class Expression extends Statement {
      * replaces this default value in the same way that any other value
      * would, ensuring that expressions are never evaluated more than once.
      * <p>
-     * See the <code>excecute</code> method for details on how
+     * See the <code>execute</code> method for details on how
      * methods are chosen using the dynamic types of the target
      * and arguments.
      *
@@ -147,6 +147,8 @@ public class Expression extends Statement {
      * @see #setValue
      *
      * @return The result of applying this method to these arguments.
+     * @throws Exception if the method with the specified methodName
+     * throws an exception
      */
     public Object getValue() throws Exception {
         if (value == unbound) {

src/share/classes/java/beans/IndexedPropertyDescriptor.java

@@ -207,6 +207,8 @@ public class IndexedPropertyDescriptor extends PropertyDescriptor {
      * Sets the method that should be used to read an indexed property value.
      *
      * @param readMethod The new indexed read method.
+     * @throws IntrospectionException if an exception occurs during
+     * introspection.
      */
     public synchronized void setIndexedReadMethod(Method readMethod)
         throws IntrospectionException {
@@ -285,6 +287,8 @@ public class IndexedPropertyDescriptor extends PropertyDescriptor {
      * Sets the method that should be used to write an indexed property value.
      *
      * @param writeMethod The new indexed write method.
+     * @throws IntrospectionException if an exception occurs during
+     * introspection.
      */
     public synchronized void setIndexedWriteMethod(Method writeMethod)
         throws IntrospectionException {

src/share/classes/java/beans/Introspector.java

 /*
- * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -93,8 +93,17 @@ import sun.reflect.misc.ReflectUtil;
 public class Introspector {
 
     // Flags that can be used to control getBeanInfo:
+    /**
+     * Flag to indicate to use of all beaninfo.
+     */
     public final static int USE_ALL_BEANINFO           = 1;
+    /**
+     * Flag to indicate to ignore immediate beaninfo.
+     */
     public final static int IGNORE_IMMEDIATE_BEANINFO  = 2;
+    /**
+     * Flag to indicate to ignore all beaninfo.
+     */
     public final static int IGNORE_ALL_BEANINFO        = 3;
 
     // Static Caches to speed up introspection.
@@ -202,7 +211,7 @@ public class Introspector {
      * If the BeanInfo class for a Java Bean has been previously Introspected
      * based on the same arguments, then the BeanInfo class is retrieved
      * from the BeanInfo cache.
-     *
+     * @return the BeanInfo for the bean
      * @param beanClass The bean class to be analyzed.
      * @param stopClass The baseclass at which to stop the analysis.  Any
      *    methods/properties/events in the stopClass or in its baseclasses

src/share/classes/java/beans/PersistenceDelegate.java

 /*
- * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -197,6 +197,7 @@ public abstract class PersistenceDelegate {
      * The default implementation, calls the <code>initialize</code>
      * method of the type's superclass.
      *
+     * @param type the type of the instances
      * @param oldInstance The instance to be copied.
      * @param newInstance The instance that is to be modified.
      * @param out The stream to which any initialization statements should be written.

src/share/classes/java/beans/PropertyChangeSupport.java

 /*
- * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -156,7 +156,7 @@ public class PropertyChangeSupport implements Serializable {
      * <code>PropertyChangeListenerProxy</code>, perform the cast, and examine
      * the parameter.
      *
-     * <pre>
+     * <pre>{@code
      * PropertyChangeListener[] listeners = bean.getPropertyChangeListeners();
      * for (int i = 0; i < listeners.length; i++) {
      *   if (listeners[i] instanceof PropertyChangeListenerProxy) {
@@ -168,7 +168,7 @@ public class PropertyChangeSupport implements Serializable {
      *     }
      *   }
      * }
-     *</pre>
+     * }</pre>
      *
      * @see PropertyChangeListenerProxy
      * @return all of the <code>PropertyChangeListeners</code> added or an

src/share/classes/java/beans/PropertyDescriptor.java

@@ -243,6 +243,7 @@ public class PropertyDescriptor extends FeatureDescriptor {
      * Sets the method that should be used to read the property value.
      *
      * @param readMethod The new read method.
+     * @throws IntrospectionException if the read method is invalid
      */
     public synchronized void setReadMethod(Method readMethod)
                                 throws IntrospectionException {
@@ -313,6 +314,7 @@ public class PropertyDescriptor extends FeatureDescriptor {
      * Sets the method that should be used to write the property value.
      *
      * @param writeMethod The new write method.
+     * @throws IntrospectionException if the write method is invalid
      */
     public synchronized void setWriteMethod(Method writeMethod)
                                 throws IntrospectionException {

src/share/classes/java/beans/Transient.java

 /*
- * Copyright (c) 2008, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -40,7 +40,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * A {@code true} value for the "transient" attribute
  * indicates to encoders derived from {@link Encoder}
  * that this feature should be ignored.
- * <p/>
+ * <p>
  * The {@code Transient} annotation may be be used
  * in any of the methods that are involved
  * in a {@link FeatureDescriptor} subclass
@@ -49,7 +49,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  * to put the annotation and it is this declaration
  * that takes precedence in the case of multiple annotations
  * being defined for the same feature.
- * <p/>
+ * <p>
  * To declare a feature non-transient in a class
  * whose superclass declares it transient,
  * use {@code @Transient(false)}.
@@ -64,5 +64,11 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 @Target({METHOD})
 @Retention(RUNTIME)
 public @interface Transient {
+    /**
+     * Returns whether or not the {@code Introspector} should
+     * construct artifacts for the annotated method.
+     * @return whether or not the {@code Introspector} should
+     * construct artifacts for the annotated method
+     */
     boolean value() default true;
 }

src/share/classes/java/beans/VetoableChangeSupport.java

 /*
- * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -42,7 +42,7 @@ import java.util.Map.Entry;
  * <p>
  * Here is an example of {@code VetoableChangeSupport} usage that follows
  * the rules and recommendations laid out in the JavaBeans&trade; specification:
- * <pre>
+ * <pre>{@code
  * public class MyBean {
  *     private final VetoableChangeSupport vcs = new VetoableChangeSupport(this);
  *
@@ -68,7 +68,7 @@ import java.util.Map.Entry;
  *
  *     [...]
  * }
- * </pre>
+ * }</pre>
  * <p>
  * A {@code VetoableChangeSupport} instance is thread-safe.
  * <p>
@@ -156,7 +156,7 @@ public class VetoableChangeSupport implements Serializable {
      * <code>VetoableChangeListenerProxy</code>, perform the cast, and examine
      * the parameter.
      *
-     * <pre>
+     * <pre>{@code
      * VetoableChangeListener[] listeners = bean.getVetoableChangeListeners();
      * for (int i = 0; i < listeners.length; i++) {
      *        if (listeners[i] instanceof VetoableChangeListenerProxy) {
@@ -168,7 +168,7 @@ public class VetoableChangeSupport implements Serializable {
      *     }
      *   }
      * }
-     *</pre>
+     * }</pre>
      *
      * @see VetoableChangeListenerProxy
      * @return all of the <code>VetoableChangeListeners</code> added or an

src/share/classes/java/beans/beancontext/BeanContext.java

 /*
- * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -64,10 +64,12 @@ public interface BeanContext extends BeanContextChild, Collection, DesignMode, V
      * and is defined by the
      * <code>java.beans.Beans.instantiate()</code> method.
      *
+     * @return a javaBean named as a child of this
+     * <code>BeanContext</code>
      * @param beanName The name of the JavaBean to instantiate
      * as a child of this <code>BeanContext</code>
-     * @throws <code>IOException</code>
-     * @throws <code>ClassNotFoundException</code> if the class identified
+     * @throws IOException if an IO problem occurs
+     * @throws ClassNotFoundException if the class identified
      * by the beanName parameter is not found
      */
     Object instantiateChild(String beanName) throws IOException, ClassNotFoundException;
@@ -83,7 +85,7 @@ public interface BeanContext extends BeanContextChild, Collection, DesignMode, V
      * @return an <code>InputStream</code> for reading the resource,
      * or <code>null</code> if the resource could not
      * be found.
-     * @throws <code>IllegalArgumentException</code> if
+     * @throws IllegalArgumentException if
      * the resource is not valid
      */
     InputStream getResourceAsStream(String name, BeanContextChild bcc) throws IllegalArgumentException;
@@ -98,7 +100,7 @@ public interface BeanContext extends BeanContextChild, Collection, DesignMode, V
      * @param bcc the specified child
      * @return a <code>URL</code> for the named
      * resource for the specified child
-     * @throws <code>IllegalArgumentException</code>
+     * @throws IllegalArgumentException
      * if the resource is not valid
      */
     URL getResource(String name, BeanContextChild bcc) throws IllegalArgumentException;
@@ -109,7 +111,7 @@ public interface BeanContext extends BeanContextChild, Collection, DesignMode, V
       * this <code>BeanContext</code> whenever it adds
       * or removes a child <code>Component</code>(s).
       *
-      * @param bcml the <code>BeanContextMembershipListener</code> to be added
+      * @param bcml the BeanContextMembershipListener to be added
       */
     void addBeanContextMembershipListener(BeanContextMembershipListener bcml);
 

src/share/classes/java/beans/beancontext/BeanContextChild.java

 /*
- * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -82,7 +82,7 @@ public interface BeanContextChild {
      * </p>
      * @param bc The <code>BeanContext</code> with which
      * to associate this <code>BeanContextChild</code>.
-     * @throws <code>PropertyVetoException</code> if the
+     * @throws PropertyVetoException if the
      * addition of the specified <code>BeanContext</code> is refused.
      */
     void setBeanContext(BeanContext bc) throws PropertyVetoException;

src/share/classes/java/beans/beancontext/BeanContextChildSupport.java

@@ -78,6 +78,7 @@ public class BeanContextChildSupport implements BeanContextChild, BeanContextSer
      * construct a BeanContextChildSupport where the JavaBean component
      * itself implements BeanContextChild, and encapsulates this, delegating
      * that interface to this implementation
+     * @param bcc the underlying bean context child
      */
 
     public BeanContextChildSupport(BeanContextChild bcc) {
@@ -94,7 +95,7 @@ public class BeanContextChildSupport implements BeanContextChild, BeanContextSer
      * this <code>BeanContextChildSupport</code>.
      * @param bc the new value to be assigned to the <code>BeanContext</code>
      * property
-     * @throws <code>PropertyVetoException</code> if the change is rejected
+     * @throws PropertyVetoException if the change is rejected
      */
     public synchronized void setBeanContext(BeanContext bc) throws PropertyVetoException {
         if (bc == beanContext) return;
@@ -361,6 +362,9 @@ public class BeanContextChildSupport implements BeanContextChild, BeanContextSer
     */
     protected VetoableChangeSupport vcSupport;
 
+    /**
+     * The bean context.
+     */
     protected transient BeanContext           beanContext;
 
    /**

src/share/classes/java/beans/beancontext/BeanContextMembershipEvent.java

 /*
- * Copyright (c) 1997, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -103,6 +103,7 @@ public class BeanContextMembershipEvent extends BeanContextEvent {
      * Is the child specified affected by the event?
      * @return <code>true</code> if affected, <code>false</code>
      * if not
+     * @param child the object to check for being affected
      */
     public boolean contains(Object child) {
         return children.contains(child);

src/share/classes/java/beans/beancontext/BeanContextServices.java

 /*
- * Copyright (c) 1998, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -60,6 +60,7 @@ public interface BeanContextServices extends BeanContext, BeanContextServicesLis
      * @param serviceClass     the service to add
      * @param serviceProvider  the <code>BeanContextServiceProvider</code>
      * associated with the service
+     * @return true if the service was successful added, false otherwise
      */
     boolean addService(Class serviceClass, BeanContextServiceProvider serviceProvider);
 
@@ -108,7 +109,7 @@ public interface BeanContextServices extends BeanContext, BeanContextServicesLis
      * @param bcsrl the
      * <code>BeanContextServiceRevokedListener</code> to notify
      * if the service should later become revoked
-     * @throws TooManyListenersException
+     * @throws TooManyListenersException if there are too many listeners
      * @return a reference to this context's named
      * Service as requested or <code>null</code>
      */

src/share/classes/java/beans/beancontext/BeanContextServicesSupport.java

 /*
- * Copyright (c) 1998, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -603,12 +603,16 @@ public class      BeanContextServicesSupport extends BeanContextSupport
                 serviceProvider = bcsp;
             }
 
+            /**
+             * Returns the service provider.
+             * @return the service provider
+             */
             protected BeanContextServiceProvider getServiceProvider() {
                 return serviceProvider;
             }
 
-            /*
-             * fields
+            /**
+             * The service provider.
              */
 
             protected BeanContextServiceProvider serviceProvider;
@@ -618,6 +622,9 @@ public class      BeanContextServicesSupport extends BeanContextSupport
          * subclasses can override this method to create new subclasses of
          * BCSSServiceProvider without having to overrride addService() in
          * order to instantiate.
+         * @param sc the class
+         * @param bcsp the service provider
+         * @return a service provider without overriding addService()
          */
 
         protected BCSSServiceProvider createBCSSServiceProvider(Class sc, BeanContextServiceProvider bcsp) {
@@ -629,7 +636,7 @@ public class      BeanContextServicesSupport extends BeanContextSupport
     /**
      * add a BeanContextServicesListener
      *
-     * @throws NullPointerException
+     * @throws NullPointerException if the argument is null
      */
 
     public void addBeanContextServicesListener(BeanContextServicesListener bcsl) {
@@ -660,6 +667,8 @@ public class      BeanContextServicesSupport extends BeanContextSupport
 
     /**
      * add a service
+     * @param serviceClass the service class
+     * @param bcsp the service provider
      */
 
     public boolean addService(Class serviceClass, BeanContextServiceProvider bcsp) {
@@ -668,6 +677,10 @@ public class      BeanContextServicesSupport extends BeanContextSupport
 
     /**
      * add a service
+     * @param serviceClass the service class
+     * @param bcsp the service provider
+     * @param fireEvent whether or not an event should be fired
+     * @return true if the service was successfully added
      */
 
     protected boolean addService(Class serviceClass, BeanContextServiceProvider bcsp, boolean fireEvent) {
@@ -709,6 +722,9 @@ public class      BeanContextServicesSupport extends BeanContextSupport
 
     /**
      * remove a service
+     * @param serviceClass the service class
+     * @param bcsp the service provider
+     * @param revokeCurrentServicesNow whether or not to revoke the service
      */
 
     public void revokeService(Class serviceClass, BeanContextServiceProvider bcsp, boolean revokeCurrentServicesNow) {
@@ -1067,6 +1083,7 @@ public class      BeanContextServicesSupport extends BeanContextSupport
 
     /**
      * Fires a <tt>BeanContextServiceEvent</tt> notifying of a new service.
+     * @param serviceClass the service class
      */
     protected final void fireServiceAdded(Class serviceClass) {
         BeanContextServiceAvailableEvent bcssae = new BeanContextServiceAvailableEvent(getBeanContextServicesPeer(), serviceClass);
@@ -1109,6 +1126,8 @@ public class      BeanContextServicesSupport extends BeanContextSupport
      * Fires a <tt>BeanContextServiceRevokedEvent</tt>
      * indicating that a particular service is
      * no longer available.
+     * @param serviceClass the service class
+     * @param revokeNow whether or not the event should be revoked now
      */
     protected final void fireServiceRevoked(Class serviceClass, boolean revokeNow) {
         Object[]                       copy;

src/share/classes/java/beans/beancontext/BeanContextSupport.java

 /*
- * Copyright (c) 1997, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -62,7 +62,6 @@ import java.util.Map;
 /**
  * This helper class provides a utility implementation of the
  * java.beans.beancontext.BeanContext interface.
- * </p>
  * <p>
  * Since this class directly implements the BeanContext interface, the class
  * can, and is intended to be used either by subclassing this implementation,
@@ -351,9 +350,8 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * of Child without having to override add() or the other Collection
      * methods that add children to the set.
      * </p>
-     *
      * @param targetChild the child to create the Child on behalf of
-     * @param peer        the peer if the tragetChild and the peer are related by an implementation of BeanContextProxy
+     * @param peer        the peer if the tragetChild and the peer are related by an implementation of BeanContextProxy     * @return Subtype-specific subclass of Child without overriding collection methods
      */
 
     protected BCSChild createBCSChild(Object targetChild, Object peer) {
@@ -492,6 +490,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * @param callChildSetBC used to indicate that
      * the child should be notified that it is no
      * longer nested in this <tt>BeanContext</tt>.
+     * @return whether or not was present before being removed
      */
     protected boolean remove(Object targetChild, boolean callChildSetBC) {
 
@@ -580,7 +579,8 @@ public class      BeanContextSupport extends BeanContextChildSupport
     /**
      * add Collection to set of Children (Unsupported)
      * implementations must synchronized on the hierarchy lock and "children" protected field
-     * @throws UnsupportedOperationException
+     * @throws UnsupportedOperationException thrown unconditionally by this implementation
+     * @return this implementation unconditionally throws {@code UnsupportedOperationException}
      */
     public boolean addAll(Collection c) {
         throw new UnsupportedOperationException();
@@ -589,7 +589,9 @@ public class      BeanContextSupport extends BeanContextChildSupport
     /**
      * remove all specified children (Unsupported)
      * implementations must synchronized on the hierarchy lock and "children" protected field
-     * @throws UnsupportedOperationException
+     * @throws UnsupportedOperationException thrown unconditionally by this implementation
+     * @return this implementation unconditionally throws {@code UnsupportedOperationException}
+
      */
     public boolean removeAll(Collection c) {
         throw new UnsupportedOperationException();
@@ -599,7 +601,8 @@ public class      BeanContextSupport extends BeanContextChildSupport
     /**
      * retain only specified children (Unsupported)
      * implementations must synchronized on the hierarchy lock and "children" protected field
-     * @throws UnsupportedOperationException
+     * @throws UnsupportedOperationException thrown unconditionally by this implementation
+     * @return this implementation unconditionally throws {@code UnsupportedOperationException}
      */
     public boolean retainAll(Collection c) {
         throw new UnsupportedOperationException();
@@ -608,7 +611,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
     /**
      * clear the children (Unsupported)
      * implementations must synchronized on the hierarchy lock and "children" protected field
-     * @throws UnsupportedOperationException
+     * @throws UnsupportedOperationException thrown unconditionally by this implementation
      */
     public void clear() {
         throw new UnsupportedOperationException();
@@ -618,7 +621,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * Adds a BeanContextMembershipListener
      *
      * @param  bcml the BeanContextMembershipListener to add
-     * @throws NullPointerException
+     * @throws NullPointerException if the argument is null
      */
 
     public void addBeanContextMembershipListener(BeanContextMembershipListener bcml) {
@@ -636,7 +639,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * Removes a BeanContextMembershipListener
      *
      * @param  bcml the BeanContextMembershipListener to remove
-     * @throws NullPointerException
+     * @throws NullPointerException if the argument is null
      */
 
     public void removeBeanContextMembershipListener(BeanContextMembershipListener bcml) {
@@ -655,7 +658,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * @param bcc  the child object making the request.
      *
      * @return  the requested resource as an InputStream
-     * @throws  NullPointerException
+     * @throws  NullPointerException if the argument is null
      */
 
     public InputStream getResourceAsStream(String name, BeanContextChild bcc) {
@@ -849,6 +852,8 @@ public class      BeanContextSupport extends BeanContextChildSupport
      *
      * This method should not however be used by subclasses to replace their
      * own implementation (if any) of writeObject().
+     * @param oos the {@code ObjectOutputStream} to use during serialization
+     * @throws IOException if serialization failed
      */
 
     protected void bcsPreSerializationHook(ObjectOutputStream oos) throws IOException {
@@ -864,6 +869,9 @@ public class      BeanContextSupport extends BeanContextChildSupport
      *
      * This method should not however be used by subclasses to replace their
      * own implementation (if any) of readObject().
+     * @param ois the {@code ObjectInputStream} to use during deserialization
+     * @throws IOException if deserialization failed
+     * @throws ClassNotFoundException if needed classes are not found
      */
 
     protected void bcsPreDeserializationHook(ObjectInputStream ois) throws IOException, ClassNotFoundException {
@@ -914,6 +922,8 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * used by readObject to deserialize a collection.
      * @param ois the ObjectInputStream to use
      * @param coll the Collection
+     * @throws IOException if deserialization failed
+     * @throws ClassNotFoundException if needed classes are not found
      */
     protected final void deserialize(ObjectInputStream ois, Collection coll) throws IOException, ClassNotFoundException {
         int count = 0;
@@ -1005,6 +1015,9 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * When an instance of this class is used as a delegate for the
      * implementation of the BeanContext protocols (and its subprotocols)
      * there exists a 'chicken and egg' problem during deserialization
+     * @param ois the ObjectInputStream to use
+     * @throws IOException if deserialization failed
+     * @throws ClassNotFoundException if needed classes are not found
      */
 
     public final void readChildren(ObjectInputStream ois) throws IOException, ClassNotFoundException {
@@ -1122,6 +1135,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * immediately prior to their being added to the BeanContext.
      * </p>
      *
+     * @param targetChild the child to create the Child on behalf of
      * @return true iff the child may be added to this BeanContext, otherwise false.
      */
 
@@ -1136,6 +1150,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * immediately prior to their being removed from the BeanContext.
      * </p>
      *
+     * @param targetChild the child to create the Child on behalf of
      * @return true iff the child may be removed from this BeanContext, otherwise false.
      */
 
@@ -1147,6 +1162,8 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * subclasses may override this method to simply extend add() semantics
      * after the child has been added and before the event notification has
      * occurred. The method is called with the child synchronized.
+     * @param child the child
+     * @param bcsc the BCSChild
      */
 
     protected void childJustAddedHook(Object child, BCSChild bcsc) {
@@ -1156,6 +1173,8 @@ public class      BeanContextSupport extends BeanContextChildSupport
      * subclasses may override this method to simply extend remove() semantics
      * after the child has been removed and before the event notification has
      * occurred. The method is called with the child synchronized.
+     * @param child the child
+     * @param bcsc the BCSChild
      */
 
     protected void childJustRemovedHook(Object child, BCSChild bcsc) {
@@ -1254,6 +1273,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
 
     /**
      * Fire a BeanContextshipEvent on the BeanContextMembershipListener interface
+     * @param bcme the event to fire
      */
 
     protected final void fireChildrenAdded(BeanContextMembershipEvent bcme) {
@@ -1267,6 +1287,7 @@ public class      BeanContextSupport extends BeanContextChildSupport
 
     /**
      * Fire a BeanContextshipEvent on the BeanContextMembershipListener interface
+     * @param bcme the event to fire
      */
 
     protected final void fireChildrenRemoved(BeanContextMembershipEvent bcme) {