2005-07-05 David Gilbert <david.gilbert@object-refinery.com>

	* javax/swing/AbstractAction.java: updated API docs,
	* javax/swing/Action.java: likewise.

1 files changed, 45 insertions, 32 deletions

diff --git a/javax/swing/Action.java b/javax/swing/Action.java
index 16b37f146..17168c3be 100644
--- a/javax/swing/Action.java
+++ b/javax/swing/Action.java
@@ -1,5 +1,5 @@
 /* Action.java --
-   Copyright (C) 2002, 2004 Free Software Foundation, Inc.
+   Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -41,99 +41,112 @@ import java.awt.event.ActionListener;
 import java.beans.PropertyChangeListener;
 
 /**
- * Action
+ * An action provides a convenient central point of control for some task
+ * that can be triggered by more than one control in a Swing user interface
+ * (for example, a menu item and a toolbar button).
+ * 
+ * @see AbstractButton#setAction(Action)
+ * 
  * @author Ronald Veldema (rveldema@cs.vu.nl)
  * @author Andrew Selkirk
  */
 public interface Action extends ActionListener {
 
   /**
-   * DEFAULT
+   * A key to access the default property for the action (this is not used).
    */
   String DEFAULT = "Default";
 
-	/**
-   * LONG_DESCRIPTION
+  /**
+   * A key to access the long description for the action.
    */
   String LONG_DESCRIPTION = "LongDescription";
 
   /**
-   * NAME
+   * A key to access the name for the action.
    */
   String NAME = "Name";
 
   /**
-   * SHORT_DESCRIPTION
+   * A key to access the short description for the action (the short
+   * description is typically used as the tool tip text).
    */
   String SHORT_DESCRIPTION = "ShortDescription";
 
   /**
-   * SMALL_ICON
+   * A key to access the icon for the action.
    */
   String SMALL_ICON = "SmallIcon";
 
   /**
-   * ACCELERATOR_KEY
+   * A key to access the {@link KeyStroke} used as the accelerator for the
+   * action.
    */
   String ACCELERATOR_KEY = "AcceleratorKey";
 
   /**
-   * ACTION_COMMAND_KEY
+   * A key to access the action command string for the action.
    */
   String ACTION_COMMAND_KEY = "ActionCommandKey";
 
   /**
-   * MNEMONIC_KEY
+   * A key to access the mnemonic for the action.
    */
   String MNEMONIC_KEY = "MnemonicKey";
 
-	/**
-   * getValue
+  /**
+   * Returns the value associated with the specified key.
+   * 
+   * @param key  the key (not <code>null</code>).
    * 
-   * @param key
-   *          TODO
-   * @returns TODO
+   * @return The value associated with the specified key, or 
+   *         <code>null</code> if the key is not found.
    */
   Object getValue(String key);
 
   /**
-   * setValue
+   * Sets the value associated with the specified key and sends a 
+   * {@link java.beans.PropertyChangeEvent} to all registered listeners.  
+   * The standard keys are defined in this interface: {@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.  
    * 
-   * @param key
-   *          TODO
-   * @param value
-   *          TODO
+   * @param key  the key (not <code>null</code>).
+   * @param value  the value (<code>null</code> permitted).
    */
   void putValue(String key, Object value);
 
   /**
-   * isEnabled
+   * Returns the flag that indicates whether or not this action is enabled.
    * 
-   * @returns TODO
+   * @return The flag.
    */
   boolean isEnabled();
 
   /**
-   * setEnabled
+   * Sets the flag that indicates whether or not this action is enabled.  If
+   * the value changes, a {@link java.beans.PropertyChangeEvent} is sent to 
+   * all registered listeners.
    * 
-   * @param b
-   *          TODO
+   * @param b  the new value of the flag.
    */
   void setEnabled(boolean b);
 
   /**
-   * addPropertyChangeListener
+   * Registers a listener to receive notification whenever one of the
+   * action's properties is modified.
    * 
-   * @param listener
-   *          TODO
+   * @param listener  the listener.
    */
   void addPropertyChangeListener(PropertyChangeListener listener);
 
   /**
-   * removePropertyChangeListener
+   * Deregisters a listener so that it no longer receives notification of
+   * changes to the action's properties. 
    * 
-   * @param listener
-   *          TODO
+   * @param listener  the listener.
    */
   void removePropertyChangeListener(PropertyChangeListener listener);