[cp-patches] FYI: API doc fixes for JComponent

[David Gilbert]

I committed this patch:

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

        * javax/swing/JComponent.java: API doc fixes all over.

Regards,

Dave Gilbert

Index: javax/swing/JComponent.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/JComponent.java,v
retrieving revision 1.52
retrieving revision 1.53
diff -u -r1.52 -r1.53
--- javax/swing/JComponent.java 4 Jul 2005 19:59:41 -0000       1.52
+++ javax/swing/JComponent.java 21 Jul 2005 08:26:09 -0000      1.53
@@ -44,6 +44,7 @@
 import java.awt.Container;
 import java.awt.Dimension;
 import java.awt.FlowLayout;
+import java.awt.FocusTraversalPolicy;
 import java.awt.Font;
 import java.awt.Graphics;
 import java.awt.Graphics2D;
@@ -71,6 +72,7 @@
 import java.util.EventListener;
 import java.util.Hashtable;
 import java.util.Locale;
+import java.util.Set;
 
 import javax.accessibility.Accessible;
 import javax.accessibility.AccessibleContext;
@@ -273,7 +275,7 @@
    * repainting of the component are usually delegated to this object. 
    *
    * @see #setUI
-   * @see #getUI
+   * @see #getUIClassID
    * @see #updateUI
    */
   protected ComponentUI ui;
@@ -361,7 +363,7 @@
    * Constant used to indicate that no condition has been assigned to a
    * particular action.
    *
-   * @see #registerKeyboardAction
+   * @see #registerKeyboardAction(ActionListener, KeyStroke, int)
    */
   public static final int UNDEFINED_CONDITION = -1;
 
@@ -369,7 +371,7 @@
    * Constant used to indicate that an action should be performed only when 
    * the component has focus.
    *
-   * @see #registerKeyboardAction
+   * @see #registerKeyboardAction(ActionListener, KeyStroke, int)
    */
   public static final int WHEN_FOCUSED = 0;
 
@@ -377,7 +379,7 @@
    * Constant used to indicate that an action should be performed only when 
    * the component is an ancestor of the component which has focus.
    *
-   * @see #registerKeyboardAction
+   * @see #registerKeyboardAction(ActionListener, KeyStroke, int)
    */
   public static final int WHEN_ANCESTOR_OF_FOCUSED_COMPONENT = 1;
 
@@ -385,7 +387,7 @@
    * Constant used to indicate that an action should be performed only when 
    * the component is in the window which has focus.
    *
-   * @see #registerKeyboardAction
+   * @see #registerKeyboardAction(ActionListener, KeyStroke, int)
    */
   public static final int WHEN_IN_FOCUSED_WINDOW = 2;
 
@@ -457,7 +459,7 @@
    *
    * @param listener The listener to unregister
    * 
-   * @see addAncestorListener
+   * @see #addAncestorListener
    */
   public void removeAncestorListener(AncestorListener listener)
   {
@@ -469,7 +471,7 @@
    *
    * @param listener The listener to register
    *
-   * @see #addPropertyChangeListener
+   * @see #addPropertyChangeListener(PropertyChangeListener)
    * @see #changeSupport
    */
   public void removePropertyChangeListener(PropertyChangeListener listener)
@@ -484,7 +486,7 @@
    * @param propertyName The property name to unregister the listener from
    * @param listener The listener to unregister
    *
-   * @see #addPropertyChangeListener
+   * @see #addPropertyChangeListener(String, PropertyChangeListener)
    * @see #changeSupport
    */
   public void removePropertyChangeListener(String propertyName,
@@ -526,7 +528,7 @@
    *
    * @param listener The listener to register
    *
-   * @see #removePropertyChangeListener
+   * @see #removePropertyChangeListener(PropertyChangeListener)
    * @see #changeSupport
    */
   public void addPropertyChangeListener(PropertyChangeListener listener)
@@ -544,7 +546,7 @@
    * @param propertyName The property name to listen to
    * @param listener The listener to register
    *
-   * @see #removePropertyChangeListener
+   * @see #removePropertyChangeListener(String, PropertyChangeListener)
    * @see #changeSupport
    */
   public void addPropertyChangeListener(String propertyName,
@@ -712,8 +714,8 @@
    * @param newValue The new value of the property
    *
    * @see #changeSupport
-   * @see #addPropertyChangeListener
-   * @see #removePropertyChangeListener
+   * @see #addPropertyChangeListener(PropertyChangeListener)
+   * @see #removePropertyChangeListener(PropertyChangeListener)
    */
   protected void firePropertyChange(String propertyName, Object oldValue,
                                     Object newValue)
@@ -745,8 +747,8 @@
    *
    * @throws PropertyVetoException if the change was vetoed by a listener
    *
-   * @see addVetoableChangeListener
-   * @see removeVetoableChangeListener
+   * @see #addVetoableChangeListener
+   * @see #removeVetoableChangeListener
    */
   protected void fireVetoableChange(String propertyName, Object oldValue,
                                     Object newValue)
@@ -945,7 +947,7 @@
   /**
    * Get the component's maximum size. If the address@hidden #maximumSize} 
property
    * has been explicitly set, it is returned. If the address@hidden 
#maximumSize}
-   * property has not been set but the address@hidden ui} property has been, 
the
+   * property has not been set but the address@hidden #ui} property has been, 
the
    * result of address@hidden ComponentUI#getMaximumSize} is returned. If 
neither
    * property has been set, the result of address@hidden 
Container#getMaximumSize}
    * is returned.
@@ -974,7 +976,7 @@
   /**
    * Get the component's minimum size. If the address@hidden #minimumSize} 
property
    * has been explicitly set, it is returned. If the address@hidden 
#minimumSize}
-   * property has not been set but the address@hidden ui} property has been, 
the
+   * property has not been set but the address@hidden #ui} property has been, 
the
    * result of address@hidden ComponentUI#getMinimumSize} is returned. If 
neither
    * property has been set, the result of address@hidden 
Container#getMinimumSize}
    * is returned.
@@ -1003,7 +1005,7 @@
   /**
    * Get the component's preferred size. If the address@hidden #preferredSize}
    * property has been explicitly set, it is returned. If the address@hidden
-   * #preferredSize} property has not been set but the address@hidden ui} 
property
+   * #preferredSize} property has not been set but the address@hidden #ui} 
property
    * has been, the result of address@hidden ComponentUI#getPreferredSize} is
    * returned. If neither property has been set, the result of address@hidden
    * Container#getPreferredSize} is returned.
@@ -1077,7 +1079,7 @@
   }
   
   /**
-   * Return the value of the address@hidden #nextFocusableComponent} property.
+   * Return the value of the <code>nextFocusableComponent</code> property.
    *
    * @return The current value of the property, or <code>null</code>
    * if none has been set.
@@ -1132,7 +1134,7 @@
   }
 
   /**
-   * Return the address@hidden #toolTip} property of this component, creating 
it and
+   * Return the <code>toolTip</code> property of this component, creating it 
and
    * setting it if it is currently <code>null</code>. This method can be
    * overridden in subclasses which wish to control the exact form of
    * tooltip created.
@@ -1149,7 +1151,7 @@
   }
 
   /**
-   * Return the location at which the address@hidden #toolTip} property should 
be
+   * Return the location at which the address@hidden #toolTipText} property 
should be
    * displayed, when triggered by a particular mouse event. 
    *
    * @param event The event the tooltip is being presented in response to
@@ -1167,7 +1169,7 @@
    *
    * @param text The new property value
    *
-   * @see #getToolTipText
+   * @see #getToolTipText()
    */
   public void setToolTipText(String text)
   {
@@ -1218,7 +1220,7 @@
 
   /**
    * Return the top level ancestral container (usually a address@hidden
-   * java.awt.Window} or address@hidden java.awt.Applet}) which this component 
is
+   * java.awt.Window} or address@hidden java.applet.Applet}) which this 
component is
    * contained within, or <code>null</code> if no ancestors exist.
    *
    * @return The top level container, if it exists
@@ -1275,9 +1277,9 @@
    * displayable, focusable, visible components.</p>
    *
    * <p>This method should not be called by clients; it is intended for
-   * focus implementations. Use address@hidden Component#requestFocus} 
instead.</p>
+   * focus implementations. Use address@hidden Component#requestFocus()} 
instead.</p>
    *
-   * @see address@hidden Component#requestFocus}
+   * @see Component#requestFocus()
    */
   public void grabFocus()
   {
@@ -1317,8 +1319,8 @@
    * @return <code>true</code> if you want this component to manage its own
    *     focus, otherwise (by default) <code>false</code>
    *
-   * @deprecated 1.4 Use address@hidden 
Component.setFocusTraversalKeys(int,Set)} and
-   *     address@hidden Container.setFocusCycleRoot(boolean)} instead
+   * @deprecated 1.4 Use address@hidden Component#setFocusTraversalKeys(int, 
Set)} and
+   *     address@hidden Container#setFocusCycleRoot(boolean)} instead
    */
   public boolean isManagingFocus()
   {
@@ -1326,7 +1328,7 @@
   }
 
   /**
-   * Return the current value of the address@hidden opaque} property. 
+   * Return the current value of the address@hidden #opaque} property. 
    *
    * @return The current property value
    */
@@ -1370,10 +1372,10 @@
 
   /**
    * Return <code>true</code> if this component is a validation root; this
-   * will cause calls to address@hidden #invalidate} in this component's 
children
+   * will cause calls to address@hidden #invalidate()} in this component's 
children
    * to be "captured" at this component, and not propagate to its parents.
    * For most components this should return <code>false</code>, but some
-   * components such as address@hidden JViewPort} will want to return
+   * components such as address@hidden JViewport} will want to return
    * <code>true</code>.
    *
    * @return Whether this component is a validation root
@@ -1386,7 +1388,7 @@
   /**
    * <p>Paint the component. This is a delicate process, and should only be
    * called from the repaint thread, under control of the address@hidden
-   * RepaintManager}. Client code should usually call address@hidden #repaint} 
to
+   * RepaintManager}. Client code should usually call address@hidden 
#repaint()} to
    * trigger painting.</p>
    *
    * <p>This method will acquire a double buffer from the address@hidden
@@ -1410,7 +1412,7 @@
    *
    * @param g The graphics context to paint with
    *
-   * @see #paintImmediately
+   * @see #paintImmediately(Rectangle)
    */
   public void paint(Graphics g)
   {
@@ -1633,18 +1635,18 @@
    * to fetch mapping tables from keystrokes to commands, and commands to
    * actions, respectively, and modify those mappings directly.
    *
-   * @param anAction The action to be registered
-   * @param aCommand The command to deliver in the delivered address@hidden
-   *     java.awt.ActionEvent}
-   * @param aKeyStroke The keystroke to register on
-   * @param aCondition One of the values address@hidden #UNDEFINED_CONDITION},
+   * @param act The action to be registered
+   * @param cmd The command to deliver in the delivered address@hidden
+   *     java.awt.event.ActionEvent}
+   * @param stroke The keystroke to register on
+   * @param cond One of the values address@hidden #UNDEFINED_CONDITION},
    *     address@hidden #WHEN_ANCESTOR_OF_FOCUSED_COMPONENT}, address@hidden 
#WHEN_FOCUSED}, or
    *     address@hidden #WHEN_IN_FOCUSED_WINDOW}, indicating the condition 
which must
    *     be met for the action to be fired
    *
    * @see #unregisterKeyboardAction
-   * @see #getConditionForKeystroke
-   * @see #resetKeyboardActiond
+   * @see #getConditionForKeyStroke
+   * @see #resetKeyboardActions
    */
   public void registerKeyboardAction(ActionListener act, 
                                      String cmd,
@@ -1724,7 +1726,7 @@
    * Return the condition that determines whether a registered action
    * occurs in response to the specified keystroke.
    *
-   * @param aKeyStroke The keystroke to return the condition of
+   * @param ks The keystroke to return the condition of
    *
    * @return One of the values address@hidden #UNDEFINED_CONDITION}, 
address@hidden
    *     #WHEN_ANCESTOR_OF_FOCUSED_COMPONENT}, address@hidden #WHEN_FOCUSED}, 
or address@hidden
@@ -1733,9 +1735,9 @@
    * @deprecated As of 1.3 KeyStrokes can be registered with multiple
    *     simultaneous conditions.
    *
-   * @see #registerKeyboardAction   
+   * @see #registerKeyboardAction(ActionListener, KeyStroke, int)   
    * @see #unregisterKeyboardAction   
-   * @see #resetKeyboardActiond
+   * @see #resetKeyboardActions
    */
   public int getConditionForKeyStroke(KeyStroke ks)
   {
@@ -1756,7 +1758,7 @@
    * Get the ActionListener (typically an address@hidden Action} object) which 
is
    * associated with a particular keystroke. 
    *
-   * @param aKeyStroke The keystroke to retrieve the action of
+   * @param ks The keystroke to retrieve the action of
    *
    * @return The action associated with the specified keystroke
    *
@@ -1833,11 +1835,11 @@
   /**
    * Remove a keyboard action registry.
    *
-   * @param stroke The keystroke to unregister
+   * @param aKeyStroke The keystroke to unregister
    *
-   * @see #registerKeyboardAction
-   * @see #getConditionForKeystroke
-   * @see #resetKeyboardActiond
+   * @see #registerKeyboardAction(ActionListener, KeyStroke, int)
+   * @see #getConditionForKeyStroke
+   * @see #resetKeyboardActions
    */
   public void unregisterKeyboardAction(KeyStroke aKeyStroke)
   {
@@ -1848,9 +1850,9 @@
   /**
    * Reset all keyboard action registries.
    *
-   * @see #registerKeyboardAction
+   * @see #registerKeyboardAction(ActionListener, KeyStroke, int)
    * @see #unregisterKeyboardAction
-   * @see #getConditionForKeystroke
+   * @see #getConditionForKeyStroke
    */
   public void resetKeyboardActions()
   {
@@ -1902,7 +1904,7 @@
    * Request focus on the default component of this component's address@hidden
    * FocusTraversalPolicy}.
    *
-   * @return The result of address@hidden #requestFocus}
+   * @return The result of address@hidden #requestFocus()}
    *
    * @deprecated Use address@hidden #requestFocus()} on the default component 
provided
    *     from the address@hidden FocusTraversalPolicy} instead.
@@ -1986,7 +1988,7 @@
   }
 
   /**
-   * Set the value of the address@hidden #enabled} property.
+   * Set the value of the <code>enabled</code> property.
    *
    * @param enable The new value of the property
    */
@@ -1998,7 +2000,7 @@
   }
 
   /**
-   * Set the value of the address@hidden #font} property.
+   * Set the value of the <code>font</code> property.
    *
    * @param f The new value of the property
    */
@@ -2008,7 +2010,7 @@
   }
 
   /**
-   * Set the value of the address@hidden #background} property.
+   * Set the value of the <code>background</code> property.
    *
    * @param bg The new value of the property
    */
@@ -2018,7 +2020,7 @@
   }
 
   /**
-   * Set the value of the address@hidden #foreground} property.
+   * Set the value of the <code>foreground</code> property.
    *
    * @param fg The new value of the property
    */
@@ -2091,7 +2093,7 @@
    *
    * @return The current value of the property
    *
-   * @see ComponentUI#setTransferHandler
+   * @see #setTransferHandler
    */
 
   public TransferHandler getTransferHandler()
@@ -2104,7 +2106,7 @@
    *
    * @param newHandler The new value of the property
    *
-   * @see ComponentUI#getTransferHandler
+   * @see #getTransferHandler
    */
 
   public void setTransferHandler(TransferHandler newHandler)
@@ -2142,7 +2144,7 @@
   }
 
   /**
-   * Call address@hidden paint}. 
+   * Call address@hidden #paint}. 
    * 
    * @param g The graphics context to paint into
    */
@@ -2155,7 +2157,7 @@
    * Get the value of the UIClassID property. This property should be a key
    * in the address@hidden UIDefaults} table managed by address@hidden 
UIManager}, the
    * value of which is the name of a class to load for the component's
-   * address@hidden ui} property.
+   * address@hidden #ui} property.
    *
    * @return A "symbolic" name which will map to a class to use for the
    * component's UI, such as <code>"ComponentUI"</code>
@@ -2169,10 +2171,10 @@
   }
 
   /**
-   * Install a new UI delegate as the component's address@hidden ui} property. 
In
-   * the process, this will call address@hidden ComponentUI.uninstallUI} on any
-   * existing value for the address@hidden ui} property, and address@hidden
-   * ComponentUI.installUI} on the new UI delegate.
+   * Install a new UI delegate as the component's address@hidden #ui} 
property. In
+   * the process, this will call address@hidden ComponentUI#uninstallUI} on any
+   * existing value for the address@hidden #ui} property, and address@hidden
+   * ComponentUI#installUI} on the new UI delegate.
    *
    * @param newUI The new UI delegate to install
    *
@@ -2198,7 +2200,7 @@
    * This method should be overridden in subclasses. In JComponent, the
    * method does nothing. In subclasses, it should a UI delegate
    * (corresponding to the symbolic name returned from address@hidden
-   * getUIClassID}) from the address@hidden UIManager}, and calls 
address@hidden setUI}
+   * #getUIClassID}) from the address@hidden UIManager}, and calls 
address@hidden #setUI}
    * with the new delegate.
    */
   public void updateUI()
@@ -2273,9 +2275,9 @@
    * situations in which it is not possible to get the focus. So developers
    * should not assume that the component has the focus until it receives
    * a address@hidden java.awt.event.FocusEvent} with a value of
-   * address@hidden java.awt.event.FocusEvent.FOCUS_GAINED}.
+   * address@hidden java.awt.event.FocusEvent#FOCUS_GAINED}.
    *
-   * @see address@hidden Component#requestFocus()}
+   * @see Component#requestFocus()
    */
   public void requestFocus()
   {
@@ -2288,15 +2290,15 @@
    * by look and feel implementations.
    *
    * You should not use this method directly. Instead you are strongly
-   * encouraged to call address@hidden #requestFocus} or address@hidden 
#requestFocusInWindow}
-   * instead.
+   * encouraged to call address@hidden #requestFocus()} or 
+   * address@hidden #requestFocusInWindow()} instead.
    *
    * @param temporary if the focus change is temporary
    *
    * @return <code>false</code> if the focus change request will definitly
    *     fail, <code>true</code> if it will likely succeed
    *
-   * @see address@hidden Component#requestFocus(boolean)}
+   * @see Component#requestFocus(boolean)
    *
    * @since 1.4
    */
@@ -2317,12 +2319,12 @@
    * situations in which it is not possible to get the focus. So developers
    * should not assume that the component has the focus until it receives
    * a address@hidden java.awt.event.FocusEvent} with a value of
-   * address@hidden java.awt.event.FocusEvent.FOCUS_GAINED}.
+   * address@hidden java.awt.event.FocusEvent#FOCUS_GAINED}.
    *
    * @return <code>false</code> if the focus change request will definitly
    *     fail, <code>true</code> if it will likely succeed
    *
-   * @see address@hidden Component#requestFocusInWindow()}
+   * @see Component#requestFocusInWindow()
    */
   public boolean requestFocusInWindow()
   {
@@ -2337,15 +2339,15 @@
    * by look and feel implementations.
    *
    * You should not use this method directly. Instead you are strongly
-   * encouraged to call address@hidden #requestFocus} or address@hidden 
#requestFocusInWindow}
-   * instead.
+   * encouraged to call address@hidden #requestFocus()} or 
+   * address@hidden #requestFocusInWindow()} instead.
    *
    * @param temporary if the focus change is temporary
    *
    * @return <code>false</code> if the focus change request will definitly
    *     fail, <code>true</code> if it will likely succeed
    *
-   * @see address@hidden Component#requestFocus(boolean)}
+   * @see Component#requestFocus(boolean)
    *
    * @since 1.4
    */
@@ -2426,7 +2428,8 @@
    * has changed.
    *
    * This method is called before the component is actually removed from
-   * its parent, so the parent is still visible through address@hidden 
#getParent}.
+   * its parent, so the parent is still visible through 
+   * address@hidden Component#getParent}.
    */
   public void removeNotify()
   {
@@ -2585,7 +2588,7 @@
   /**
    * Prints this component to the given Graphics context. A call to this
    * method results in calls to the methods address@hidden #printComponent},
-   * address@hidden #printBorder} and address@hidden printChildren} in this 
order.
+   * address@hidden #printBorder} and address@hidden #printChildren} in this 
order.
    *
    * Double buffering is temporarily turned off so the painting goes directly
    * to the supplied Graphics context.