changeset 10493:b27b4a607bca

8042284: Add block tags for @return and @param to swing plaf classes Reviewed-by: prr
author ssides
date Tue, 29 Jul 2014 12:55:08 +0400
parents 6ad4626c1a10
children eb8dc6f39e88
files src/share/classes/javax/swing/plaf/ComboBoxUI.java src/share/classes/javax/swing/plaf/ComponentUI.java src/share/classes/javax/swing/plaf/FileChooserUI.java src/share/classes/javax/swing/plaf/LayerUI.java src/share/classes/javax/swing/plaf/OptionPaneUI.java src/share/classes/javax/swing/plaf/PopupMenuUI.java src/share/classes/javax/swing/plaf/SplitPaneUI.java src/share/classes/javax/swing/plaf/TextUI.java src/share/classes/javax/swing/plaf/TreeUI.java
diffstat 9 files changed, 152 insertions(+), 48 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/javax/swing/plaf/ComboBoxUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/ComboBoxUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -37,16 +37,25 @@
 
     /**
      * Set the visibility of the popup
+     *
+     * @param c a {@code JComboBox}
+     * @param v a {@code boolean} determining the visibilty of the popup
      */
     public abstract void setPopupVisible( JComboBox<?> c, boolean v );
 
     /**
      * Determine the visibility of the popup
+     *
+     * @param c a {@code JComboBox}
+     * @return true if popup of the {@code JComboBox} is visible
      */
     public abstract boolean isPopupVisible( JComboBox<?> c );
 
     /**
      * Determine whether or not the combo box itself is traversable
+     *
+     * @param c a {@code JComboBox}
+     * @return true if the given {@code JComboBox} is traversable
      */
     public abstract boolean isFocusTraversable( JComboBox<?> c );
 }
--- a/src/share/classes/javax/swing/plaf/ComponentUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/ComponentUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -173,7 +173,8 @@
      *          this argument is often ignored,
      *          but might be used if the UI object is stateless
      *          and shared by multiple components
-     *
+     * @return a {@code Dimension} object containing given component's preferred
+     *         size appropriate for the look and feel
      * @see javax.swing.JComponent#getPreferredSize
      * @see java.awt.LayoutManager#preferredLayoutSize
      */
@@ -240,7 +241,8 @@
      *          and shared by multiple components
      * @param x the <i>x</i> coordinate of the point
      * @param y the <i>y</i> coordinate of the point
-     *
+     * @return {@code true} if the specified {@code x,y} location is contained
+     *         within the look and feel's defined shape for the given component
      * @see javax.swing.JComponent#contains
      * @see java.awt.Component#contains
      */
@@ -258,6 +260,9 @@
      * stateful, then it should return a new instance per component.
      * The default implementation of this method throws an error, as it
      * should never be invoked.
+     *
+     * @param c a {@code JComponent} for which to create a UI delegate
+     * @return a {@code ComponentUI} object for {@code c}
      */
     public static ComponentUI createUI(JComponent c) {
         throw new Error("ComponentUI.createUI not implemented.");
@@ -332,8 +337,9 @@
      * <code>Component.AccessibleAWTComponent.getAccessibleChildrenCount()</code> instead
      * of this method.
      *
+     * @param c {@code JComponent} for which to get count of accessible children
+     * @return the number of accessible children in the object
      * @see #getAccessibleChild
-     * @return the number of accessible children in the object
      */
     public int getAccessibleChildrenCount(JComponent c) {
         return SwingUtilities.getAccessibleChildrenCount(c);
@@ -351,9 +357,10 @@
      * <code>Component.AccessibleAWTComponent.getAccessibleChild()</code> instead of
      * this method.
      *
-     * @see #getAccessibleChildrenCount
+     * @param c a {@code JComponent} for which to get a child object
      * @param i zero-based index of child
      * @return the <code>i</code>th <code>Accessible</code> child of the object
+     * @see #getAccessibleChildrenCount
      */
     public Accessible getAccessibleChild(JComponent c, int i) {
         return SwingUtilities.getAccessibleChild(c, i);
--- a/src/share/classes/javax/swing/plaf/FileChooserUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/FileChooserUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -52,6 +52,8 @@
      * <code>JFileChooser</code> will use this button as default button
      * for dialog windows.
      *
+     * @param fc the {@code JFileChooser} whose default button is requested
+     * @return the default JButton for current look and feel
      * @since 1.7
      */
     public JButton getDefaultButton(JFileChooser fc) {
--- a/src/share/classes/javax/swing/plaf/LayerUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/LayerUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -716,7 +716,7 @@
      * @param y  the y value of the region to be painted
      * @param width  the width of the region to be painted
      * @param height  the height of the region to be painted
-     *
+     * @param l  a {@code JLayer} component
      * @see JComponent#paintImmediately(int, int, int, int)
      */
     public void paintImmediately(int x, int y, int width, int height, JLayer<? extends V> l) {
--- a/src/share/classes/javax/swing/plaf/OptionPaneUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/OptionPaneUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 1998, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,12 +38,18 @@
     /**
      * Requests the component representing the default value to have
      * focus.
+     *
+     * @param op a {@code JOptionPane}
      */
     public abstract void selectInitialValue(JOptionPane op);
 
     /**
      * Returns true if the user has supplied instances of Component for
      * either the options or message.
+     *
+     * @param op a {@code JOptionPane}
+     * @return {@code true} if the given {@code JOptionPane} contains user
+     *         created {@code Component}s
      */
     public abstract boolean containsCustomComponents(JOptionPane op);
 }
--- a/src/share/classes/javax/swing/plaf/PopupMenuUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/PopupMenuUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2000, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,6 +39,11 @@
 
 public abstract class PopupMenuUI extends ComponentUI {
     /**
+     * Returns whether or not the given {@code MouseEvent} is the popup menu
+     * trigger event for the platform
+     *
+     * @param e a {@code MouseEvent}
+     * @return true if the {@code MouseEvent e} is the popup menu trigger
      * @since 1.3
      */
     public boolean isPopupTrigger(MouseEvent e) {
--- a/src/share/classes/javax/swing/plaf/SplitPaneUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/SplitPaneUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 1998, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,32 +38,49 @@
     /**
      * Messaged to relayout the JSplitPane based on the preferred size
      * of the children components.
+     *
+     * @param jc a {@code JSplitPane}
      */
     public abstract void resetToPreferredSizes(JSplitPane jc);
 
     /**
      * Sets the location of the divider to location.
+     *
+     * @param jc a {@code JSplitPane}
+     * @param location an integer specifying the location of the divider
      */
     public abstract void setDividerLocation(JSplitPane jc, int location);
 
     /**
      * Returns the location of the divider.
+     *
+     * @param jc a {@code JSplitPane}
+     * @return an integer specifying the location of the divider
      */
     public abstract int getDividerLocation(JSplitPane jc);
 
     /**
      * Returns the minimum possible location of the divider.
+     *
+     * @param jc a {@code JSplitPane}
+     * @return and integer specifying the minimum location of the divider
      */
     public abstract int getMinimumDividerLocation(JSplitPane jc);
 
     /**
      * Returns the maximum possible location of the divider.
+     *
+     * @param jc a {@code JSplitPane}
+     * @return an integer specifying the maximum location of the divider
      */
     public abstract int getMaximumDividerLocation(JSplitPane jc);
 
     /**
      * Messaged after the JSplitPane the receiver is providing the look
      * and feel for paints its children.
+     *
+     * @param jc a {@code JSplitPane}
+     * @param g the {@code Graphics} context
      */
     public abstract void finishedPaintingChildren(JSplitPane jc, Graphics g);
 }
--- a/src/share/classes/javax/swing/plaf/TextUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/TextUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -42,8 +42,9 @@
      * Converts the given location in the model to a place in
      * the view coordinate system.
      *
+     * @param t the text component for which this UI is installed
      * @param pos  the local location in the model to translate &gt;= 0
-     * @return the coordinates as a rectangle
+     * @return the coordinates as a {@code Rectangle}
      * @exception BadLocationException  if the given position does not
      *   represent a valid location in the associated document
      */
@@ -53,8 +54,10 @@
      * Converts the given location in the model to a place in
      * the view coordinate system.
      *
+     * @param t the text component for which this UI is installed
      * @param pos  the local location in the model to translate &gt;= 0
-     * @return the coordinates as a rectangle
+     * @param bias the bias for the position
+     * @return the coordinates as a {@code Rectangle}
      * @exception BadLocationException  if the given position does not
      *   represent a valid location in the associated document
      */
@@ -64,6 +67,7 @@
      * Converts the given place in the view coordinate system
      * to the nearest representative location in the model.
      *
+     * @param t the text component for which this UI is installed
      * @param pt  the location in the view to translate.  This
      *   should be in the same coordinate system as the mouse
      *   events.
@@ -75,6 +79,7 @@
      * Provides a mapping from the view coordinate space to the logical
      * coordinate space of the model.
      *
+     * @param t the text component for which this UI is installed
      * @param pt the location in the view to translate.
      *           This should be in the same coordinate system
      *           as the mouse events.
@@ -117,6 +122,7 @@
      * Causes the portion of the view responsible for the
      * given part of the model to be repainted.
      *
+     * @param t the text component for which this UI is installed
      * @param p0 the beginning of the range &gt;= 0
      * @param p1 the end of the range &gt;= p0
      */
@@ -126,8 +132,13 @@
      * Causes the portion of the view responsible for the
      * given part of the model to be repainted.
      *
+     * @param t the text component for which this UI is installed
      * @param p0 the beginning of the range &gt;= 0
      * @param p1 the end of the range &gt;= p0
+     * @param firstBias the bias of the first character position, toward the
+     *        previous character or the next character
+     * @param secondBias the bias of the second character position, toward the
+     *        previous character or the next character
      */
     public abstract void damageRange(JTextComponent t, int p0, int p1,
                                      Position.Bias firstBias,
@@ -139,6 +150,7 @@
      * things like the commands available, stream readers and
      * writers, etc.
      *
+     * @param t the text component for which this UI is installed
      * @return the editor kit binding
      */
     public abstract EditorKit getEditorKit(JTextComponent t);
@@ -149,13 +161,18 @@
      * can be traversed to determine how the model is being
      * represented spatially.
      *
-     * @return the view
+     * @param t the text component for which this UI is installed
+     * @return a {@code View} with the allocation of the associated
+     *         text component
      */
     public abstract View getRootView(JTextComponent t);
 
     /**
      * Returns the string to be used as the tooltip at the passed in location.
      *
+     * @param t  the text component for which this UI is installed
+     * @param pt a {@code Point} specifying location for which to get a tooltip
+     * @return a {@code String} containing the tooltip
      * @see javax.swing.text.JTextComponent#getToolTipText
      * @since 1.4
      */
--- a/src/share/classes/javax/swing/plaf/TreeUI.java	Tue Jul 29 12:45:24 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/TreeUI.java	Tue Jul 29 12:55:08 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 1998, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,68 +38,109 @@
 public abstract class TreeUI extends ComponentUI
 {
     /**
-      * Returns the Rectangle enclosing the label portion that the
-      * last item in path will be drawn into.  Will return null if
-      * any component in path is currently valid.
-      */
+     * Returns the Rectangle enclosing the label portion that the
+     * last item in path will be drawn into.  Will return null if
+     * any component in path is currently valid.
+     *
+     * @param tree the {@code JTree} for {@code path}
+     * @param path the {@code TreePath} identifying the node
+     * @return the {@code Rectangle} enclosing the label portion that the
+     *         last item in path will be drawn into, {@code null} if any
+     *         component in path is currently valid.
+     */
     public abstract Rectangle getPathBounds(JTree tree, TreePath path);
 
     /**
-      * Returns the path for passed in row.  If row is not visible
-      * null is returned.
-      */
+     * Returns the path for passed in row.  If row is not visible
+     * null is returned.
+     *
+     * @param tree a {@code JTree} object
+     * @param row an integer specifying a row
+     * @return the {@code path} for {@code row} or {@code null} if {@code row}
+     *         is not visible
+     */
     public abstract TreePath getPathForRow(JTree tree, int row);
 
     /**
-      * Returns the row that the last item identified in path is visible
-      * at.  Will return -1 if any of the elements in path are not
-      * currently visible.
-      */
+     * Returns the row that the last item identified in path is visible
+     * at.  Will return -1 if any of the elements in path are not
+     * currently visible.
+     *
+     * @param tree the {@code JTree} for {@code path}
+     * @param path the {@code TreePath} object to look in
+     * @return an integer specifying the row at which the last item
+     *         identified is visible, -1 if any of the elements in
+     *         {@code path} are not currently visible
+     */
     public abstract int getRowForPath(JTree tree, TreePath path);
 
     /**
-      * Returns the number of rows that are being displayed.
-      */
+     * Returns the number of rows that are being displayed.
+     *
+     * @param tree the {@code JTree} for which to count rows
+     * @return an integer specifying the number of row being displayed
+     */
     public abstract int getRowCount(JTree tree);
 
     /**
-      * Returns the path to the node that is closest to x,y.  If
-      * there is nothing currently visible this will return null, otherwise
-      * it'll always return a valid path.  If you need to test if the
-      * returned object is exactly at x, y you should get the bounds for
-      * the returned path and test x, y against that.
-      */
+     * Returns the path to the node that is closest to x,y.  If
+     * there is nothing currently visible this will return null, otherwise
+     * it'll always return a valid path.  If you need to test if the
+     * returned object is exactly at x, y you should get the bounds for
+     * the returned path and test x, y against that.
+     *
+     * @param tree a {@code JTree} object
+     * @param x an integer giving the number of pixels horizontally from the
+     *        left edge of the display area
+     * @param y an integer giving the number of pixels vertically from the top
+     *        of the display area, minus any top margin
+     * @return the {@code TreePath} node closest to {@code x,y} or {@code null}
+     *         if there is nothing currently visible
+     */
     public abstract TreePath getClosestPathForLocation(JTree tree, int x,
                                                        int y);
 
     /**
-      * Returns true if the tree is being edited.  The item that is being
-      * edited can be returned by getEditingPath().
-      */
+     * Returns true if the tree is being edited.  The item that is being
+     * edited can be returned by getEditingPath().
+     *
+     * @param tree a {@code JTree} object
+     * @return true if {@code tree} is being edited
+     */
     public abstract boolean isEditing(JTree tree);
 
     /**
-      * Stops the current editing session.  This has no effect if the
-      * tree isn't being edited.  Returns true if the editor allows the
-      * editing session to stop.
-      */
+     * Stops the current editing session.  This has no effect if the
+     * tree isn't being edited.  Returns true if the editor allows the
+     * editing session to stop.
+     *
+     * @param tree a {@code JTree} object
+     * @return true if the editor allows the editing session to stop
+     */
     public abstract boolean stopEditing(JTree tree);
 
     /**
-      * Cancels the current editing session. This has no effect if the
-      * tree isn't being edited.  Returns true if the editor allows the
-      * editing session to stop.
-      */
+     * Cancels the current editing session. This has no effect if the
+     * tree isn't being edited.
+     *
+     * @param tree a {@code JTree} object
+     */
     public abstract void cancelEditing(JTree tree);
 
     /**
-      * Selects the last item in path and tries to edit it.  Editing will
-      * fail if the CellEditor won't allow it for the selected item.
-      */
+     * Selects the last item in path and tries to edit it.  Editing will
+     * fail if the CellEditor won't allow it for the selected item.
+     *
+     * @param tree the {@code JTree} being edited
+     * @param path the {@code TreePath} to be edited
+     */
     public abstract void startEditingAtPath(JTree tree, TreePath path);
 
     /**
      * Returns the path to the element that is being edited.
+     *
+     * @param tree the {@code JTree} for which to return a path
+     * @return a {@code TreePath} containing the path to {@code tree}
      */
     public abstract TreePath getEditingPath(JTree tree);
 }