changeset 10099:4b7e8552b328

8046595: fix doclint issues in swing classes, part 2 of 4 Reviewed-by: pchelko Contributed-by: Andrei Eremeev <andrei.eremeev@oracle.com>
author yan
date Wed, 18 Jun 2014 17:31:01 +0400
parents 5e7143c1abc1
children bb18a27ea6de
files src/share/classes/javax/swing/AbstractButton.java src/share/classes/javax/swing/Action.java src/share/classes/javax/swing/FocusManager.java src/share/classes/javax/swing/JComboBox.java src/share/classes/javax/swing/JProgressBar.java src/share/classes/javax/swing/JRadioButton.java src/share/classes/javax/swing/JToolBar.java src/share/classes/javax/swing/SwingUtilities.java
diffstat 8 files changed, 170 insertions(+), 9 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/javax/swing/AbstractButton.java	Wed Jun 18 03:29:58 2014 -0700
+++ b/src/share/classes/javax/swing/AbstractButton.java	Wed Jun 18 17:31:01 2014 +0400
@@ -947,6 +947,7 @@
      * <p>
      * This is a JavaBeans bound property.
      *
+     * @param iconTextGap the space between icon and text if these properties are set.
      * @since 1.4
      * @see #getIconTextGap
      * @beaninfo
@@ -1337,6 +1338,7 @@
      * that of the <code>Action</code>.
      *
      * @param a the button's action
+     * @return the {@code PropertyChangeListener}
      * @since 1.3
      * @see Action
      * @see #setAction
@@ -2070,12 +2072,20 @@
         }
     }
 
-
+    /**
+     * Returns {@code ActionListener} that is added to model.
+     *
+     * @return the {@code ActionListener}
+     */
     protected ActionListener createActionListener() {
         return getHandler();
     }
 
-
+    /**
+     * Returns {@code ItemListener} that is added to model.
+     *
+     * @return the {@code ItemListener}
+     */
     protected ItemListener createItemListener() {
         return getHandler();
     }
@@ -2148,7 +2158,7 @@
         return listenerList.getListeners(ItemListener.class);
     }
 
-   /**
+    /**
      * Returns an array (length 1) containing the label or
      * <code>null</code> if the button is not selected.
      *
@@ -2164,6 +2174,12 @@
         return selectedObjects;
     }
 
+    /**
+     * Initialization of the {@code AbstractButton}.
+     *
+     * @param text  the text of the button
+     * @param icon  the Icon image to display on the button
+     */
     protected void init(String text, Icon icon) {
         if(text != null) {
             setText(text);
--- a/src/share/classes/javax/swing/Action.java	Wed Jun 18 03:29:58 2014 -0700
+++ b/src/share/classes/javax/swing/Action.java	Wed Jun 18 17:31:01 2014 +0400
@@ -337,6 +337,9 @@
     /**
      * Gets one of this object's properties
      * using the associated key.
+     *
+     * @param key a {@code String} containing the key
+     * @return the {@code Object} value
      * @see #putValue
      */
     public Object getValue(String key);
--- a/src/share/classes/javax/swing/FocusManager.java	Wed Jun 18 03:29:58 2014 -0700
+++ b/src/share/classes/javax/swing/FocusManager.java	Wed Jun 18 17:31:01 2014 +0400
@@ -140,6 +140,7 @@
      * Returns whether the application has invoked
      * <code>disableSwingFocusManager()</code>.
      *
+     * @return {@code true} if focus manager is enabled.
      * @see #disableSwingFocusManager
      * @deprecated As of 1.4, replaced by
      *   <code>KeyboardFocusManager.getDefaultFocusTraversalPolicy()</code>
--- a/src/share/classes/javax/swing/JComboBox.java	Wed Jun 18 03:29:58 2014 -0700
+++ b/src/share/classes/javax/swing/JComboBox.java	Wed Jun 18 17:31:01 2014 +0400
@@ -232,6 +232,13 @@
         updateUI();
     }
 
+    /**
+     * Registers ancestor listener so that it will receive
+     * {@code AncestorEvents} when it or any of its ancestors
+     * move or are made visible or invisible.
+     * Events are also sent when the component or its ancestors are added
+     * or removed from the containment hierarchy.
+     */
     protected void installAncestorListener() {
         addAncestorListener(new AncestorListener(){
                                 public void ancestorAdded(AncestorEvent event){ hidePopup();}
@@ -812,6 +819,8 @@
 
     /**
      * Sets the visibility of the popup.
+     *
+     * @param v if {@code true} shows the popup, otherwise, hides the popup.
      */
     public void setPopupVisible(boolean v) {
         getUI().setPopupVisible(this, v);
@@ -1144,6 +1153,7 @@
      * that of the <code>Action</code>.
      *
      * @param a the combobox's action
+     * @return the {@code PropertyChangeListener}
      * @since 1.3
      * @see Action
      * @see #setAction
@@ -1357,6 +1367,8 @@
      *
      * @param keyChar a char, typically this is a keyboard key
      *                  typed by the user
+     * @return {@code true} if there is an item corresponding to that character.
+     *         Otherwise, returns {@code false}.
      */
     public boolean selectWithKeyChar(char keyChar) {
         int index;
@@ -1443,6 +1455,7 @@
      * selection. Typically, the first selection with a matching first
      * character becomes the selected item.
      *
+     * @param aManager a key selection manager
      * @beaninfo
      *       expert: true
      *  description: The objects that changes the selection when a key is pressed.
--- a/src/share/classes/javax/swing/JProgressBar.java	Wed Jun 18 03:29:58 2014 -0700
+++ b/src/share/classes/javax/swing/JProgressBar.java	Wed Jun 18 17:31:01 2014 +0400
@@ -665,6 +665,7 @@
      * to the {@code ChangeListener}s that have been added directly to the
      * progress bar.
      *
+     * @return the instance of a custom {@code ChangeListener} implementation.
      * @see #changeListener
      * @see #fireStateChanged
      * @see javax.swing.event.ChangeListener
--- a/src/share/classes/javax/swing/JRadioButton.java	Wed Jun 18 03:29:58 2014 -0700
+++ b/src/share/classes/javax/swing/JRadioButton.java	Wed Jun 18 17:31:01 2014 +0400
@@ -118,6 +118,7 @@
      * Creates a radiobutton where properties are taken from the
      * Action supplied.
      *
+     * @param a an {@code Action}
      * @since 1.3
      */
     public JRadioButton(Action a) {
@@ -175,6 +176,8 @@
      *
      * @param text  the string displayed on the radio button
      * @param icon  the image that the button should display
+     * @param selected if {@code true}, the button is initially selected
+     *                 otherwise, the button is initially unselected
      */
     public JRadioButton (String text, Icon icon, boolean selected) {
         super(text, icon, selected);
--- a/src/share/classes/javax/swing/JToolBar.java	Wed Jun 18 03:29:58 2014 -0700
+++ b/src/share/classes/javax/swing/JToolBar.java	Wed Jun 18 17:31:01 2014 +0400
@@ -161,6 +161,8 @@
 
     /**
      * Returns the tool bar's current UI.
+     *
+     * @return the tool bar's current UI.
      * @see #setUI
      */
     public ToolBarUI getUI() {
@@ -555,7 +557,8 @@
      * or <code>null</code> if the default
      * property change listener for the control is desired.
      *
-     * @return <code>null</code>
+     * @param b a {@code JButton}
+     * @return {@code null}
      */
     protected PropertyChangeListener createActionChangeListener(JButton b) {
         return null;
--- a/src/share/classes/javax/swing/SwingUtilities.java	Wed Jun 18 03:29:58 2014 -0700
+++ b/src/share/classes/javax/swing/SwingUtilities.java	Wed Jun 18 17:31:01 2014 +0400
@@ -103,15 +103,23 @@
     }
 
     /**
-     * Return true if <code>a</code> contains <code>b</code>
+     * Return {@code true} if @{code a} contains {@code b}
+     *
+     * @param a the first rectangle
+     * @param b the second rectangle
+     *
+     * @return {@code true} if @{code a} contains {@code b}
      */
-    public static final boolean isRectangleContainingRectangle(Rectangle a,Rectangle b) {
+    public static boolean isRectangleContainingRectangle(Rectangle a,Rectangle b) {
         return b.x >= a.x && (b.x + b.width) <= (a.x + a.width) &&
                 b.y >= a.y && (b.y + b.height) <= (a.y + a.height);
     }
 
     /**
-     * Return the rectangle (0,0,bounds.width,bounds.height) for the component <code>aComponent</code>
+     * Return the rectangle (0,0,bounds.width,bounds.height) for the component {@code aComponent}
+     *
+     * @param aComponent a component
+     * @return the local bounds for the component {@code aComponent}
      */
     public static Rectangle getLocalBounds(Component aComponent) {
         Rectangle b = new Rectangle(aComponent.getBounds());
@@ -165,6 +173,12 @@
      * root component coordinate system.
      * If both <code>source</code> and <code>destination</code> are {@code null}, return <code>aPoint</code>
      * without any conversion.
+     *
+     * @param source the source component
+     * @param aPoint the point
+     * @param destination the destination component
+     *
+     * @return the converted coordinate
      */
     public static Point convertPoint(Component source,Point aPoint,Component destination) {
         Point p;
@@ -196,6 +210,13 @@
      * root component coordinate system.
      * If both <code>source</code> and <code>destination</code> are {@code null}, return <code>(x,y)</code>
      * without any conversion.
+     *
+     * @param source the source component
+     * @param x the x-coordinate of the point
+     * @param y the y-coordinate of the point
+     * @param destination the destination component
+     *
+     * @return the converted coordinate
      */
     public static Point convertPoint(Component source,int x, int y,Component destination) {
         Point point = new Point(x,y);
@@ -211,6 +232,12 @@
      * root component coordinate system.
      * If both <code>source</code> and <code>destination</code> are {@code null}, return <code>aRectangle</code>
      * without any conversion.
+     *
+     * @param source the source component
+     * @param aRectangle a rectangle
+     * @param destination the destination component
+     *
+     * @return the converted rectangle
      */
     public static Rectangle convertRectangle(Component source,Rectangle aRectangle,Component destination) {
         Point point = new Point(aRectangle.x,aRectangle.y);
@@ -222,6 +249,12 @@
      * Convenience method for searching above <code>comp</code> in the
      * component hierarchy and returns the first object of class <code>c</code> it
      * finds. Can return {@code null}, if a class <code>c</code> cannot be found.
+     *
+     * @param c the class of a component
+     * @param comp the component
+     *
+     * @return the ancestor of the {@code comp},
+     *         or {@code null} if {@code c} cannot be found.
      */
     public static Container getAncestorOfClass(Class<?> c, Component comp)
     {
@@ -238,6 +271,12 @@
      * Convenience method for searching above <code>comp</code> in the
      * component hierarchy and returns the first object of <code>name</code> it
      * finds. Can return {@code null}, if <code>name</code> cannot be found.
+     *
+     * @param name the name of a component
+     * @param comp the component
+     *
+     * @return the ancestor of the {@code comp},
+     *         or {@code null} if {@code name} cannot be found.
      */
     public static Container getAncestorNamed(String name, Component comp) {
         if(comp == null || name == null)
@@ -260,6 +299,8 @@
      * @param parent the root component to begin the search
      * @param x the x target location
      * @param y the y target location
+     *
+     * @return the deepest component
      */
     public static Component getDeepestComponentAt(Component parent, int x, int y) {
         if (!parent.contains(x, y)) {
@@ -297,6 +338,12 @@
      * to <code>destination</code> if destination is non-{@code null}
      * use the translateMouseEvent() method to translate a mouse event from
      * one component to another without changing the source.
+     *
+     * @param source the source component
+     * @param sourceEvent the source mouse event
+     * @param destination the destination component
+     *
+     * @return the new mouse event
      */
     public static MouseEvent convertMouseEvent(Component source,
                                                MouseEvent sourceEvent,
@@ -456,7 +503,11 @@
     }
 
     /**
-     * Return <code>true</code> if a component <code>a</code> descends from a component <code>b</code>
+     * Return {@code true} if a component {@code a} descends from a component {@code b}
+     *
+     * @param a the first component
+     * @param b the second component
+     * @return {@code true} if a component {@code a} descends from a component {@code b}
      */
     public static boolean isDescendingFrom(Component a,Component b) {
         if(a == b)
@@ -531,6 +582,12 @@
      * Convenience returning an array of rect representing the regions within
      * <code>rectA</code> that do not overlap with <code>rectB</code>. If the
      * two Rects do not overlap, returns an empty array
+     *
+     * @param rectA the first rectangle
+     * @param rectB the second rectangle
+     *
+     * @return an array of rectangles representing the regions within {@code rectA}
+     *         that do not overlap with {@code rectB}.
      */
     public static Rectangle[] computeDifference(Rectangle rectA,Rectangle rectB) {
         if (rectB == null || !rectA.intersects(rectB) || isRectangleContainingRectangle(rectB,rectA)) {
@@ -841,6 +898,21 @@
      * relative to the viewR rectangle.
      * The JComponents orientation (LEADING/TRAILING) will also be taken
      * into account and translated into LEFT/RIGHT values accordingly.
+     *
+     * @param c the component
+     * @param fm the instance of {@code FontMetrics}
+     * @param text the text
+     * @param icon the icon
+     * @param verticalAlignment the vertical alignment
+     * @param horizontalAlignment the horizontal alignment
+     * @param verticalTextPosition the vertical text position
+     * @param horizontalTextPosition the horizontal text position
+     * @param viewR the available rectangle
+     * @param iconR the rectangle for the icon
+     * @param textR the rectangle for the text
+     * @param textIconGap the gap between text and icon
+     *
+     * @return the possibly clipped version of the compound labels string
      */
     public static String layoutCompoundLabel(JComponent c,
                                              FontMetrics fm,
@@ -910,6 +982,20 @@
      * values in horizontalTextPosition (they will default to RIGHT) and in
      * horizontalAlignment (they will default to CENTER).
      * Use the other version of layoutCompoundLabel() instead.
+     *
+     * @param fm the instance of {@code FontMetrics}
+     * @param text the text
+     * @param icon the icon
+     * @param verticalAlignment the vertical alignment
+     * @param horizontalAlignment the horizontal alignment
+     * @param verticalTextPosition the vertical text position
+     * @param horizontalTextPosition the horizontal text position
+     * @param viewR the available rectangle
+     * @param iconR the rectangle for the icon
+     * @param textR the rectangle for the text
+     * @param textIconGap the gap between text and icon
+     *
+     * @return the possibly clipped version of the compound labels string
      */
     public static String layoutCompoundLabel(
         FontMetrics fm,
@@ -1219,6 +1305,8 @@
      * A simple minded look and feel change: ask each node in the tree
      * to <code>updateUI()</code> -- that is, to initialize its UI property
      * with the current look and feel.
+     *
+     * @param c the component
      */
     public static void updateComponentTreeUI(Component c) {
         updateComponentTreeUI0(c);
@@ -1284,6 +1372,7 @@
      * <p>
      * Unlike the rest of Swing, this method can be invoked from any thread.
      *
+     * @param doRun the instance of {@code Runnable}
      * @see #invokeAndWait
      */
     public static void invokeLater(Runnable doRun) {
@@ -1334,6 +1423,7 @@
      * As of 1.3 this method is just a cover for
      * <code>java.awt.EventQueue.invokeAndWait()</code>.
      *
+     * @param doRun the instance of {@code Runnable}
      * @exception  InterruptedException if we're interrupted while waiting for
      *             the event dispatching thread to finish executing
      *             <code>doRun.run()</code>
@@ -1374,6 +1464,7 @@
      * Component.AccessibleAWTComponent.getAccessibleIndexInParent() instead
      * of using this method.
      *
+     * @param c the component
      * @return -1 of this object does not have an accessible parent.
      * Otherwise, the index of the child in its accessible parent.
      */
@@ -1386,6 +1477,8 @@
      * local coordinate <code>Point</code>, if one exists.
      * Otherwise returns <code>null</code>.
      *
+     * @param c the component
+     * @param p the local coordinate
      * @return the <code>Accessible</code> at the specified location,
      *    if it exists; otherwise <code>null</code>
      */
@@ -1431,6 +1524,7 @@
      * Component.AccessibleAWTComponent.getAccessibleIndexInParent() instead
      * of using this method.
      *
+     * @param c the component
      * @return an instance of AccessibleStateSet containing the current state
      * set of the object
      * @see AccessibleState
@@ -1448,6 +1542,7 @@
      * Component.AccessibleAWTComponent.getAccessibleIndexInParent() instead
      * of using this method.
      *
+     * @param c the component
      * @return the number of accessible children in the object.
      */
     public static int getAccessibleChildrenCount(Component c) {
@@ -1461,6 +1556,7 @@
      * Component.AccessibleAWTComponent.getAccessibleIndexInParent() instead
      * of using this method.
      *
+     * @param c the component
      * @param i zero-based index of child
      * @return the nth Accessible child of the object
      */
@@ -1502,6 +1598,8 @@
     /**
      * If c is a JRootPane descendant return its JRootPane ancestor.
      * If c is a RootPaneContainer then return its JRootPane.
+     *
+     * @param c the component
      * @return the JRootPane for Component c or {@code null}.
      */
     public static JRootPane getRootPane(Component c) {
@@ -1519,6 +1617,8 @@
 
     /**
      * Returns the root component for the current component tree.
+     *
+     * @param c the component
      * @return the first ancestor of c that's a Window or the last Applet ancestor
      */
     public static Component getRoot(Component c) {
@@ -1616,6 +1716,14 @@
      * This will return true if <code>action</code> is non-{@code null} and
      * actionPerformed is invoked on it.
      *
+     * @param action an action
+     * @param ks a key stroke
+     * @param event a key event
+     * @param sender a sender
+     * @param modifiers action modifiers
+     * @return {@code true} if {@code action} is non-{@code null} and
+     *         actionPerformed is invoked on it.
+     *
      * @since 1.3
      */
     public static boolean notifyAction(Action action, KeyStroke ks,
@@ -1672,6 +1780,9 @@
      * to <code>uiInputMap</code>. If <code>uiInputMap</code> is {@code null},
      * this removes any previously installed UI InputMap.
      *
+     * @param component a component
+     * @param type a type
+     * @param uiInputMap an {@code InputMap}
      * @since 1.3
      */
     public static void replaceUIInputMap(JComponent component, int type,
@@ -1694,6 +1805,8 @@
      * to <code>uiActionMap</code>. If <code>uiActionMap</code> is {@code null},
      * this removes any previously installed UI ActionMap.
      *
+     * @param component a component
+     * @param uiActionMap an {@code ActionMap}
      * @since 1.3
      */
     public static void replaceUIActionMap(JComponent component,
@@ -1714,9 +1827,14 @@
     /**
      * Returns the InputMap provided by the UI for condition
      * <code>condition</code> in component <code>component</code>.
-     * <p>This will return {@code null} if the UI has not installed a InputMap
+     * <p>This will return {@code null} if the UI has not installed an InputMap
      * of the specified type.
      *
+     * @param component a component
+     * @param condition a condition
+     * @return the {@code ActionMap} provided by the UI for {@code condition}
+     *         in the component, or {@code null} if the UI has not installed
+     *         an InputMap of the specified type.
      * @since 1.3
      */
     public static InputMap getUIInputMap(JComponent component, int condition) {
@@ -1736,6 +1854,9 @@
      * in component <code>component</code>.
      * <p>This will return {@code null} if the UI has not installed an ActionMap.
      *
+     * @param component a component
+     * @return the {@code ActionMap} provided by the UI in the component,
+     *         or {@code null} if the UI has not installed an ActionMap.
      * @since 1.3
      */
     public static ActionMap getUIActionMap(JComponent component) {