2006-03-03 David Gilbert <david.gilbert@object-refinery.com>

	* javax/swing/AbstractAction.java: Updated API docs all over,
	* javax/swing/AbstractCellRenderer.java: Minor reformatting, plus
	(stopCellEditing): Minor API doc correction,
	* javax/swing/UnsupportedLookAndFeelException.java
	(UnsupportedLookAndFeelException): Changed argument name, updated API
	docs.

4 files changed, 100 insertions, 47 deletions

diff --git a/ChangeLog b/ChangeLog
index 59f6dc668..b393d3d14 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2006-03-03  David Gilbert  <david.gilbert@object-refinery.com>
+
+	* javax/swing/AbstractAction.java: Updated API docs all over,
+	* javax/swing/AbstractCellRenderer.java: Minor reformatting, plus
+	(stopCellEditing): Minor API doc correction,
+	* javax/swing/UnsupportedLookAndFeelException.java
+	(UnsupportedLookAndFeelException): Changed argument name, updated API
+	docs.
+
 2006-03-03  Roman Kennke  <kennke@aicas.com>
 
 	* javax/swing/plaf/basic/BasicHTML.java
diff --git a/javax/swing/AbstractAction.java b/javax/swing/AbstractAction.java
index 25db58ed0..4a2334570 100644
--- a/javax/swing/AbstractAction.java
+++ b/javax/swing/AbstractAction.java
@@ -38,6 +38,7 @@ exception statement from your version. */
 
 package javax.swing;
 
+import java.beans.PropertyChangeEvent;
 import java.beans.PropertyChangeListener;
 import java.io.IOException;
 import java.io.ObjectInputStream;
@@ -82,8 +83,9 @@ public abstract class AbstractAction
   }
 
   /**
-   * Creates a new action with the specified name.  All other properties are
-   * initialised to <code>null</code>.
+   * Creates a new action with the specified name.  The name is stored as a 
+   * property with the key {@link Action#NAME}, and no other properties are
+   * initialised.
    *
    * @param name  the name (<code>null</code> permitted).
    */
@@ -93,8 +95,10 @@ public abstract class AbstractAction
   }
 
   /**
-   * Creates a new action with the specified name and icon.  All other 
-   * properties are initialised to <code>null</code>.
+   * Creates a new action with the specified name and icon.  The name is stored
+   * as a property with the key {@link Action#NAME}, the icon is stored as a
+   * property with the key {@link Action#SMALL_ICON}, and no other properties 
+   * are initialised.
    *
    * @param name  the name (<code>null</code> permitted).
    * @param icon  the icon (<code>null</code> permitted).
@@ -132,11 +136,12 @@ public abstract class AbstractAction
   }
 
   /**
-   * clone
+   * Returns a clone of the action.
    *
-   * @return Object
+   * @return A clone of the action.
    *
-   * @exception CloneNotSupportedException TODO
+   * @exception CloneNotSupportedException if there is a problem cloning the
+   *            action.
    */
   protected Object clone() throws CloneNotSupportedException
   {
@@ -152,6 +157,8 @@ public abstract class AbstractAction
    * 
    * @return The value associated with the specified key, or 
    *         <code>null</code> if the key is not found.
+   *         
+   * @see #putValue(String, Object)
    */
   public Object getValue(String key)
   {
@@ -161,11 +168,17 @@ public abstract class AbstractAction
   /**
    * Sets the value associated with the specified key and sends a 
    * {@link java.beans.PropertyChangeEvent} to all registered listeners.  
-   * The standard keys are: {@link #NAME}, {@link #SHORT_DESCRIPTION}, 
-   * {@link #LONG_DESCRIPTION}, {@link #SMALL_ICON}, 
-   * {@link #ACTION_COMMAND_KEY}, {@link #ACCELERATOR_KEY} and 
-   * {@link #MNEMONIC_KEY}. Any existing value associated with the key will be 
-   * overwritten.
+   * The standard keys are: 
+   * <ul>
+   * <li>{@link #NAME}</li>
+   * <li>{@link #SHORT_DESCRIPTION}</li> 
+   * <li>{@link #LONG_DESCRIPTION}</li>
+   * <li>{@link #SMALL_ICON}</li> 
+   * <li>{@link #ACTION_COMMAND_KEY}</li>
+   * <li>{@link #ACCELERATOR_KEY}</li> 
+   * <li>{@link #MNEMONIC_KEY}</li>
+   * </ul>
+   * Any existing value associated with the key will be overwritten.
    * 
    * @param key  the key (not <code>null</code>).
    * @param value  the value (<code>null</code> permitted).
@@ -184,6 +197,8 @@ public abstract class AbstractAction
    * Returns the flag that indicates whether or not the action is enabled.
    *
    * @return The flag.
+   * 
+   * @see #setEnabled(boolean)
    */
   public boolean isEnabled()
   {
@@ -193,9 +208,12 @@ public abstract class AbstractAction
   /**
    * Sets the flag that indicates whether or not the action is enabled and, if
    * the value of the flag changed from the previous setting, sends a 
-   * {@link java.beans.PropertyChangeEvent} to all registered listeners.
+   * {@link java.beans.PropertyChangeEvent} to all registered listeners (using 
+   * the property name 'enabled').
    *
    * @param enabled  the new flag value.
+   * 
+   * @see #isEnabled()
    */
   public void setEnabled(boolean enabled)
   {
@@ -207,8 +225,11 @@ public abstract class AbstractAction
   }
 
   /**
-   * getKeys
-   * @returns Object[]
+   * Returns an array of the keys for the property values that have been 
+   * defined via the {@link #putValue(String, Object)} method (or the class
+   * constructor).
+   * 
+   * @return An array of keys.
    */
   public Object[] getKeys()
   {
@@ -216,12 +237,12 @@ public abstract class AbstractAction
   }
 
   /**
-   * This method fires a PropertyChangeEvent given the propertyName 
-   * and the old and new values.
+   * Sends a {@link PropertyChangeEvent} for the named property to all 
+   * registered listeners.
    *
-   * @param propertyName The property that changed.
-   * @param oldValue The old value of the property.
-   * @param newValue The new value of the property.
+   * @param propertyName  the property name.
+   * @param oldValue  the old value of the property.
+   * @param newValue  the new value of the property.
    */
   protected void firePropertyChange(String propertyName, Object oldValue,
                                     Object newValue)
@@ -230,22 +251,27 @@ public abstract class AbstractAction
   }
   
   /**
-   * This convenience method fires a PropertyChangeEvent given 
-   * the propertyName and the old and new values.
+   * Sends a {@link PropertyChangeEvent} for the named property to all
+   * registered listeners.  This private method is called by the 
+   * {@link #setEnabled(boolean)} method.
    *
-   * @param propertyName The property that changed.
-   * @param oldValue The old value of the property.
-   * @param newValue The new value of the property.
+   * @param propertyName  the property name.
+   * @param oldValue  the old value of the property.
+   * @param newValue  the new value of the property.
    */
-  private void firePropertyChange(String propertyName, boolean oldValue, boolean newValue)
+  private void firePropertyChange(String propertyName, boolean oldValue, 
+                                  boolean newValue)
   {
     changeSupport.firePropertyChange(propertyName, oldValue, newValue);
   }
 
   /**
-   * addPropertyChangeListener
+   * Registers a listener to receive {@link PropertyChangeEvent} notifications
+   * from this action.
    *
-   * @param listener the listener to add
+   * @param listener the listener.
+   * 
+   * @see #removePropertyChangeListener(PropertyChangeListener)
    */
   public void addPropertyChangeListener(PropertyChangeListener listener)
   {
@@ -253,9 +279,12 @@ public abstract class AbstractAction
   }
 
   /**
-   * removePropertyChangeListener
+   * Deregisters a listener so that it no longer receives 
+   * {@link PropertyChangeEvent} notifications from this action.
    *
-   * @param listener the listener to remove
+   * @param listener the listener.
+   * 
+   * @see #addPropertyChangeListener(PropertyChangeListener)
    */
   public void removePropertyChangeListener(PropertyChangeListener listener)
   {
@@ -265,7 +294,7 @@ public abstract class AbstractAction
   /**
    * Returns all registered listeners.
    *
-   * @return array of listeners.
+   * @return An array of listeners.
    * 
    * @since 1.4
    */
diff --git a/javax/swing/AbstractCellEditor.java b/javax/swing/AbstractCellEditor.java
index 4ed15809a..df0d3db12 100644
--- a/javax/swing/AbstractCellEditor.java
+++ b/javax/swing/AbstractCellEditor.java
@@ -1,5 +1,5 @@
 /* AbstractCellEditor.java --
-   Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
+   Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -69,10 +69,11 @@ public abstract class AbstractCellEditor
   /**
    * Creates a new instance of AbstractCellEditor.
    */
-  public AbstractCellEditor() {
+  public AbstractCellEditor() 
+  {
     listenerList = new EventListenerList();
     changeEvent = new ChangeEvent(this);
-  } // AbstractCellEditor()
+  }
 
   /**
    * Returns <code>true</code> if the cell is editable using
@@ -84,9 +85,10 @@ public abstract class AbstractCellEditor
    * @return <code>true</code> if the cell is editable using
    *     <code>event</code>, <code>false</code> if it's not
    */
-  public boolean isCellEditable(EventObject event) {
+  public boolean isCellEditable(EventObject event) 
+  {
     return true;
-  } // isCellEditable()
+  } 
 
   /**
    * Returns <code>true</code> if the editing cell should be selected,
@@ -99,29 +101,32 @@ public abstract class AbstractCellEditor
    * @return <code>true</code> if the editing cell should be selected,
    *     <code>false</code> otherwise
    */
-  public boolean shouldSelectCell(EventObject event) {
+  public boolean shouldSelectCell(EventObject event) 
+  {
     return true;
-  } // shouldSelectCell()
+  }
 
   /**
    * Stop editing the cell and accept any partial value that has been entered
    * into the cell.
    *
-   * @returns <code>true</code> if editing has been stopped successfully,
+   * @return <code>true</code> if editing has been stopped successfully,
    *     <code>false</code>otherwise
    */
-  public boolean stopCellEditing() {
+  public boolean stopCellEditing() 
+  {
     fireEditingStopped();
     return true;
-  } // stopCellEditing()
+  }
 
   /**
    * Stop editing the cell and do not accept any partial value that has
    * been entered into the cell.
    */
-  public void cancelCellEditing() {
+  public void cancelCellEditing() 
+  {
     fireEditingCanceled();
-  } // cancelCellEditing()
+  } 
 
   /**
    * Adds a CellEditorListener to the list of CellEditorListeners of this
diff --git a/javax/swing/UnsupportedLookAndFeelException.java b/javax/swing/UnsupportedLookAndFeelException.java
index f99c0ac19..b65119a00 100644
--- a/javax/swing/UnsupportedLookAndFeelException.java
+++ b/javax/swing/UnsupportedLookAndFeelException.java
@@ -1,5 +1,5 @@
 /* UnsupportedLookAndFeelException.java -- 
-   Copyright (C) 2002 Free Software Foundation, Inc.
+   Copyright (C) 2002, 2006, Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -37,11 +37,21 @@ exception statement from your version. */
 
 package javax.swing;
 
-
+/**
+ * Thrown by the {@link UIManager#setLookAndFeel(LookAndFeel)} method when the
+ * specified look and feel is not supported on the current platform.
+ * 
+ * @see LookAndFeel#isSupportedLookAndFeel()
+ */
 public class UnsupportedLookAndFeelException extends Exception
 {
-  public UnsupportedLookAndFeelException(String a)
+  /**
+   * Creates a new exception instance with the specified message.
+   * 
+   * @param s  the exception message.
+   */
+  public UnsupportedLookAndFeelException(String s)
   {
-    super(a);
+    super(s);
   }
 }