--- a/jdk/src/share/classes/java/beans/PropertyEditor.java	Wed Jun 18 19:15:23 2008 +0400
+++ b/jdk/src/share/classes/java/beans/PropertyEditor.java	Thu Jun 19 18:03:43 2008 +0400
@@ -204,20 +204,21 @@
     //----------------------------------------------------------------------
 
     /**
-     * Register a listener for the PropertyChange event.  When a
-     * PropertyEditor changes its value it should fire a PropertyChange
-     * event on all registered PropertyChangeListeners, specifying the
-     * null value for the property name and itself as the source.
+     * Adds a listener for the value change.
+     * When the property editor changes its value
+     * it should fire a {@link PropertyChangeEvent}
+     * on all registered {@link PropertyChangeListener}s,
+     * specifying the {@code null} value for the property name
+     * and itself as the source.
      *
-     * @param listener  An object to be invoked when a PropertyChange
-     *          event is fired.
+     * @param listener  the {@link PropertyChangeListener} to add
      */
     void addPropertyChangeListener(PropertyChangeListener listener);
 
     /**
-     * Remove a listener for the PropertyChange event.
+     * Removes a listener for the value change.
      *
-     * @param listener  The PropertyChange listener to be removed.
+     * @param listener  the {@link PropertyChangeListener} to remove
      */
     void removePropertyChangeListener(PropertyChangeListener listener);
 

--- a/jdk/src/share/classes/java/beans/PropertyEditorSupport.java	Wed Jun 18 19:15:23 2008 +0400
+++ b/jdk/src/share/classes/java/beans/PropertyEditorSupport.java	Thu Jun 19 18:03:43 2008 +0400
@@ -233,11 +233,20 @@
     //----------------------------------------------------------------------
 
     /**
-     * Register a listener for the PropertyChange event.  The class will
-     * fire a PropertyChange value whenever the value is updated.
+     * Adds a listener for the value change.
+     * When the property editor changes its value
+     * it should fire a {@link PropertyChangeEvent}
+     * on all registered {@link PropertyChangeListener}s,
+     * specifying the {@code null} value for the property name.
+     * If the source property is set,
+     * it should be used as the source of the event.
+     * <p>
+     * The same listener object may be added more than once,
+     * and will be called as many times as it is added.
+     * If {@code listener} is {@code null},
+     * no exception is thrown and no action is taken.
      *
-     * @param listener  An object to be invoked when a PropertyChange
-     *          event is fired.
+     * @param listener  the {@link PropertyChangeListener} to add
      */
     public synchronized void addPropertyChangeListener(
                                 PropertyChangeListener listener) {
@@ -248,9 +257,14 @@
     }
 
     /**
-     * Remove a listener for the PropertyChange event.
+     * Removes a listener for the value change.
+     * <p>
+     * If the same listener was added more than once,
+     * it will be notified one less time after being removed.
+     * If {@code listener} is {@code null}, or was never added,
+     * no exception is thrown and no action is taken.
      *
-     * @param listener  The PropertyChange listener to be removed.
+     * @param listener  the {@link PropertyChangeListener} to remove
      */
     public synchronized void removePropertyChangeListener(
                                 PropertyChangeListener listener) {