[cp-patches] FYI: Added API docs to (javax.swing.) Action and AbstractAction

[David Gilbert]

I committed this patch to add some API doc comments:

2005-07-05  David Gilbert  <address@hidden>

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

Regards,

Dave Gilbert

Index: javax/swing/AbstractAction.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/AbstractAction.java,v
retrieving revision 1.14
diff -u -r1.14 AbstractAction.java
--- javax/swing/AbstractAction.java     2 Jul 2005 20:32:46 -0000       1.14
+++ javax/swing/AbstractAction.java     5 Jul 2005 14:51:56 -0000
@@ -48,7 +48,8 @@
 import javax.swing.event.SwingPropertyChangeSupport;
 
 /**
- * AbstractAction
+ * A base class for implementing the address@hidden Action} interface.
+ * 
  * @author     Andrew Selkirk
  * @version    1.0
  */
@@ -58,12 +59,12 @@
   private static final long serialVersionUID = -6803159439231523484L;
 
   /**
-   * enabled
+   * A flag that indicates whether or not the action is enabled.
    */
   protected boolean enabled = true;
   
   /**
-   * changeSupport
+   * Provides support for property change event notification. 
    */
   protected SwingPropertyChangeSupport changeSupport =
     new SwingPropertyChangeSupport(this);
@@ -74,7 +75,8 @@
   private transient HashMap store = new HashMap();
 
   /**
-   * Constructor AbstractAction
+   * Creates a new action with an empty string for the name.  All other 
+   * properties are initialised to <code>null</code>
    */
   public AbstractAction()
   {
@@ -82,9 +84,10 @@
   }
 
   /**
-   * Constructor AbstractAction
+   * Creates a new action with the specified name.  All other properties are
+   * initialised to <code>null</code>.
    *
-   * @param name TODO
+   * @param name  the name (<code>null</code> permitted).
    */
   public AbstractAction(String name)
   {
@@ -92,10 +95,11 @@
   }
 
   /**
-   * Constructor AbstractAction
+   * Creates a new action with the specified name and icon.  All other 
+   * properties are initialised to <code>null</code>.
    *
-   * @param name TODO
-   * @param icon TODO
+   * @param name  the name (<code>null</code> permitted).
+   * @param icon  the icon (<code>null</code> permitted).
    */
   public AbstractAction(String name, Icon icon)
   {
@@ -144,11 +148,12 @@
   }
 
   /**
-   * Returns a value for a given key from the built-in store.
-   *
-   * @param key the key to get the value for
-   *
-   * @return Object
+   * Returns the value associated with the specified key.
+   * 
+   * @param key  the key (not <code>null</code>).
+   * 
+   * @return The value associated with the specified key, or 
+   *         <code>null</code> if the key is not found.
    */
   public Object getValue(String key)
   {
@@ -156,10 +161,16 @@
   }
 
   /**
-   * Puts a key/value pair into the built-in store.
-   *
-   * @param key the key
-   * @param value the value
+   * Sets the value associated with the specified key and sends a 
+   * address@hidden java.beans.PropertyChangeEvent} to all registered 
listeners.  
+   * The standard keys are: address@hidden #NAME}, address@hidden 
#SHORT_DESCRIPTION}, 
+   * address@hidden #LONG_DESCRIPTION}, address@hidden #SMALL_ICON}, 
+   * address@hidden #ACTION_COMMAND_KEY}, address@hidden #ACCELERATOR_KEY} and 
+   * address@hidden #MNEMONIC_KEY}. 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).
    */
   public void putValue(String key, Object value)
   {
@@ -172,9 +183,9 @@
   }
 
   /**
-   * isEnabled
+   * Returns the flag that indicates whether or not the action is enabled.
    *
-   * @return boolean
+   * @return The flag.
    */
   public boolean isEnabled()
   {
@@ -182,9 +193,11 @@
   }
 
   /**
-   * setEnabled
+   * 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 
+   * address@hidden java.beans.PropertyChangeEvent} to all registered 
listeners.
    *
-   * @param enabled TODO
+   * @param enabled  the new flag value.
    */
   public void setEnabled(boolean enabled)
   {
Index: javax/swing/Action.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/Action.java,v
retrieving revision 1.9
diff -u -r1.9 Action.java
--- javax/swing/Action.java     2 Jul 2005 20:32:46 -0000       1.9
+++ javax/swing/Action.java     5 Jul 2005 14:51:56 -0000
@@ -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.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 (address@hidden)
  * @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 address@hidden 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 
+   * address@hidden java.beans.PropertyChangeEvent} to all registered 
listeners.  
+   * The standard keys are defined in this interface: address@hidden #NAME}, 
+   * address@hidden #SHORT_DESCRIPTION}, address@hidden #LONG_DESCRIPTION}, 
+   * address@hidden #SMALL_ICON}, address@hidden #ACTION_COMMAND_KEY}, 
+   * address@hidden #ACCELERATOR_KEY} and address@hidden #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 address@hidden 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);