changeset 10391:a13a49fc1810

8049808: Fix doclint warnings from javax.swing.plaf.basic package, 3 of 7 Reviewed-by: pchelko
author aeremeev
date Thu, 10 Jul 2014 17:20:56 +0400
parents b2e756f77a2e
children 6c875efda606
files src/share/classes/javax/swing/plaf/basic/BasicBorders.java src/share/classes/javax/swing/plaf/basic/BasicListUI.java src/share/classes/javax/swing/plaf/basic/BasicMenuItemUI.java src/share/classes/javax/swing/plaf/basic/BasicProgressBarUI.java src/share/classes/javax/swing/plaf/basic/BasicSplitPaneUI.java
diffstat 5 files changed, 599 insertions(+), 101 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/javax/swing/plaf/basic/BasicBorders.java	Thu Jul 10 15:08:50 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/basic/BasicBorders.java	Thu Jul 10 17:20:56 2014 +0400
@@ -45,6 +45,11 @@
 
 public class BasicBorders {
 
+    /**
+     * Returns a border instance for a {@code JButton}.
+     *
+     * @return a border instance for a {@code JButton}
+     */
     public static Border getButtonBorder() {
         UIDefaults table = UIManager.getLookAndFeelDefaults();
         Border buttonBorder = new BorderUIResource.CompoundBorderUIResource(
@@ -57,6 +62,11 @@
         return buttonBorder;
     }
 
+    /**
+     * Returns a border instance for a {@code JRadioButton}.
+     *
+     * @return a border instance for a {@code JRadioButton}
+     */
     public static Border getRadioButtonBorder() {
         UIDefaults table = UIManager.getLookAndFeelDefaults();
         Border radioButtonBorder = new BorderUIResource.CompoundBorderUIResource(
@@ -69,6 +79,11 @@
         return radioButtonBorder;
     }
 
+    /**
+     * Returns a border instance for a {@code JToggleButton}.
+     *
+     * @return a border instance for a {@code JToggleButton}
+     */
     public static Border getToggleButtonBorder() {
         UIDefaults table = UIManager.getLookAndFeelDefaults();
         Border toggleButtonBorder = new BorderUIResource.CompoundBorderUIResource(
@@ -81,6 +96,11 @@
         return toggleButtonBorder;
     }
 
+    /**
+     * Returns a border instance for a {@code JMenuBar}.
+     *
+     * @return a border instance for a {@code JMenuBar}
+     */
     public static Border getMenuBarBorder() {
         UIDefaults table = UIManager.getLookAndFeelDefaults();
         Border menuBarBorder = new BasicBorders.MenuBarBorder(
@@ -90,6 +110,11 @@
         return menuBarBorder;
     }
 
+    /**
+     * Returns a border instance for a {@code JSplitPane}.
+     *
+     * @return a border instance for a {@code JSplitPane}
+     */
     public static Border getSplitPaneBorder() {
         UIDefaults table = UIManager.getLookAndFeelDefaults();
         Border splitPaneBorder = new BasicBorders.SplitPaneBorder(
@@ -99,7 +124,9 @@
     }
 
     /**
-     * Returns a border instance for a JSplitPane divider
+     * Returns a border instance for a {@code JSplitPane} divider.
+     *
+     * @return a border instance for a {@code JSplitPane} divider
      * @since 1.3
      */
     public static Border getSplitPaneDividerBorder() {
@@ -110,6 +137,11 @@
         return splitPaneBorder;
     }
 
+    /**
+     * Returns a border instance for a {@code JTextField}.
+     *
+     * @return a border instance for a {@code JTextField}
+     */
     public static Border getTextFieldBorder() {
         UIDefaults table = UIManager.getLookAndFeelDefaults();
         Border textFieldBorder = new BasicBorders.FieldBorder(
@@ -120,12 +152,22 @@
         return textFieldBorder;
     }
 
+    /**
+     * Returns a border instance for a {@code JProgressBar}.
+     *
+     * @return a border instance for a {@code JProgressBar}
+     */
     public static Border getProgressBarBorder() {
         UIDefaults table = UIManager.getLookAndFeelDefaults();
         Border progressBarBorder = new BorderUIResource.LineBorderUIResource(Color.green, 2);
         return progressBarBorder;
     }
 
+    /**
+     * Returns a border instance for a {@code JInternalFrame}.
+     *
+     * @return a border instance for a {@code JInternalFrame}
+     */
     public static Border getInternalFrameBorder() {
         UIDefaults table = UIManager.getLookAndFeelDefaults();
         Border internalFrameBorder = new BorderUIResource.CompoundBorderUIResource(
@@ -147,6 +189,14 @@
     @SuppressWarnings("serial") // Superclass is not serializable across versions
     public static class RolloverButtonBorder extends ButtonBorder {
 
+        /**
+         * Constructs a new instance of a {@code RolloverButtonBorder}.
+         *
+         * @param shadow a color of shadow
+         * @param darkShadow a color of dark shadow
+         * @param highlight a color of highlight
+         * @param lightHighlight a color of light highlight
+         */
         public RolloverButtonBorder(Color shadow, Color darkShadow,
                                   Color highlight, Color lightHighlight) {
             super(shadow, darkShadow, highlight, lightHighlight);
@@ -227,13 +277,36 @@
         }
     }
 
+    /**
+     * Draws a border around a button.
+     */
     @SuppressWarnings("serial") // Superclass is not serializable across versions
    public static class ButtonBorder extends AbstractBorder implements UIResource {
+        /**
+         * The color of shadow.
+         */
         protected Color shadow;
+        /**
+         * The color of dark shadow.
+         */
         protected Color darkShadow;
+        /**
+         * The color of highlight.
+         */
         protected Color highlight;
+        /**
+         * The color of light highlight.
+         */
         protected Color lightHighlight;
 
+        /**
+         * Constructs a new instance of a {@code ButtonBorder}.
+         *
+         * @param shadow a color of shadow
+         * @param darkShadow a color of dark shadow
+         * @param highlight a color of highlight
+         * @param lightHighlight a color of light highlight
+         */
         public ButtonBorder(Color shadow, Color darkShadow,
                             Color highlight, Color lightHighlight) {
             this.shadow = shadow;
@@ -270,9 +343,20 @@
 
     }
 
+    /**
+     * Draws the border around a toggle button.
+     */
     @SuppressWarnings("serial") // Superclass is not serializable across versions
     public static class ToggleButtonBorder extends ButtonBorder {
 
+        /**
+         * Constructs a new instance of a {@code ToggleButtonBorder}.
+         *
+         * @param shadow a color of shadow
+         * @param darkShadow a color of dark shadow
+         * @param highlight a color of highlight
+         * @param lightHighlight a color of light highlight
+         */
         public ToggleButtonBorder(Color shadow, Color darkShadow,
                                   Color highlight, Color lightHighlight) {
             super(shadow, darkShadow, highlight, lightHighlight);
@@ -292,9 +376,20 @@
         }
     }
 
+    /**
+     * Draws the border around a radio button.
+     */
     @SuppressWarnings("serial") // Superclass is not serializable across versions
     public static class RadioButtonBorder extends ButtonBorder {
 
+        /**
+         * Constructs a new instance of a {@code RadioButtonBorder}.
+         *
+         * @param shadow a color of shadow
+         * @param darkShadow a color of dark shadow
+         * @param highlight a color of highlight
+         * @param lightHighlight a color of light highlight
+         */
         public RadioButtonBorder(Color shadow, Color darkShadow,
                                  Color highlight, Color lightHighlight) {
             super(shadow, darkShadow, highlight, lightHighlight);
@@ -329,11 +424,26 @@
         }
     }
 
+    /**
+     * Draws the border around a menu bar.
+     */
     @SuppressWarnings("serial") // Superclass is not serializable across versions
     public static class MenuBarBorder extends AbstractBorder implements UIResource {
+        /**
+         * The color of shadow.
+         */
         private Color shadow;
+        /**
+         * The color of highlight.
+         */
         private Color highlight;
 
+        /**
+         * Constructs a new instance of a {@code MenuBarBorder}.
+         *
+         * @param shadow a color of shadow
+         * @param highlight a color of highlight
+         */
         public MenuBarBorder(Color shadow, Color highlight) {
             this.shadow = shadow;
             this.highlight = highlight;
@@ -356,6 +466,9 @@
         }
     }
 
+    /**
+     * Draws the border around components which support margins.
+     */
     @SuppressWarnings("serial") // Superclass is not serializable across versions
     public static class MarginBorder extends AbstractBorder implements UIResource {
         public Insets getBorderInsets(Component c, Insets insets)       {
@@ -384,13 +497,36 @@
         }
     }
 
+    /**
+     * Draws the border around a field.
+     */
     @SuppressWarnings("serial") // Superclass is not serializable across versions
     public static class FieldBorder extends AbstractBorder implements UIResource {
+        /**
+         * The color of shadow.
+         */
         protected Color shadow;
+        /**
+         * The color of dark shadow.
+         */
         protected Color darkShadow;
+        /**
+         * The color of highlight.
+         */
         protected Color highlight;
+        /**
+         * The color of light highlight.
+         */
         protected Color lightHighlight;
 
+        /**
+         * Constructs a new instance of a {@code FieldBorder}.
+         *
+         * @param shadow a color of shadow
+         * @param darkShadow a color of dark shadow
+         * @param highlight a color of highlight
+         * @param lightHighlight a color of light highlight
+         */
         public FieldBorder(Color shadow, Color darkShadow,
                            Color highlight, Color lightHighlight) {
             this.shadow = shadow;
@@ -509,9 +645,21 @@
      * also install a border on the divider (property SplitPaneDivider.border).
      */
     public static class SplitPaneBorder implements Border, UIResource {
+        /**
+         * The color of highlight
+         */
         protected Color highlight;
+        /**
+         * The color of shadow
+         */
         protected Color shadow;
 
+        /**
+         * Constructs a new instance of a {@code SplitPaneBorder}.
+         *
+         * @param highlight a color of highlight
+         * @param shadow a color of shadow
+         */
         public SplitPaneBorder(Color highlight, Color shadow) {
             this.highlight = highlight;
             this.shadow = shadow;
--- a/src/share/classes/javax/swing/plaf/basic/BasicListUI.java	Thu Jul 10 15:08:50 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/basic/BasicListUI.java	Thu Jul 10 17:20:56 2014 +0400
@@ -59,20 +59,53 @@
     private static final StringBuilder BASELINE_COMPONENT_KEY =
         new StringBuilder("List.baselineComponent");
 
+    /**
+     * The instance of {@code JList}.
+     */
     protected JList<Object> list = null;
+    /**
+     * The instance of {@code CellRendererPane}.
+     */
     protected CellRendererPane rendererPane;
 
     // Listeners that this UI attaches to the JList
+    /**
+     * {@code FocusListener} that attached to {@code JList}.
+     */
     protected FocusListener focusListener;
+    /**
+     * {@code MouseInputListener} that attached to {@code JList}.
+     */
     protected MouseInputListener mouseInputListener;
+    /**
+     * {@code ListSelectionListener} that attached to {@code JList}.
+     */
     protected ListSelectionListener listSelectionListener;
+    /**
+     * {@code ListDataListener} that attached to {@code JList}.
+     */
     protected ListDataListener listDataListener;
+    /**
+     * {@code PropertyChangeListener} that attached to {@code JList}.
+     */
     protected PropertyChangeListener propertyChangeListener;
     private Handler handler;
 
+    /**
+     * The array of cells' height
+     */
     protected int[] cellHeights = null;
+    /**
+     * The height of cell.
+     */
     protected int cellHeight = -1;
+    /**
+     * The width of cell.
+     */
     protected int cellWidth = -1;
+    /**
+     * The value represents changes to {@code JList} model.
+     */
     protected int updateLayoutStateNeeded = modelChanged;
     /**
      * Height of the list. When asked to paint, if the current size of
@@ -131,12 +164,33 @@
      * models length changed, are handled similarly, see DataListener.
      */
 
+    /**
+     * The bit relates to model changed property.
+     */
     protected final static int modelChanged = 1 << 0;
+    /**
+     * The bit relates to selection model changed property.
+     */
     protected final static int selectionModelChanged = 1 << 1;
+    /**
+     * The bit relates to font changed property.
+     */
     protected final static int fontChanged = 1 << 2;
+    /**
+     * The bit relates to fixed cell width changed property.
+     */
     protected final static int fixedCellWidthChanged = 1 << 3;
+    /**
+     * The bit relates to fixed cell height changed property.
+     */
     protected final static int fixedCellHeightChanged = 1 << 4;
+    /**
+     * The bit relates to prototype cell value changed property.
+     */
     protected final static int prototypeCellValueChanged = 1 << 5;
+    /**
+     * The bit relates to cell renderer changed property.
+     */
     protected final static int cellRendererChanged = 1 << 6;
     private final static int layoutOrientationChanged = 1 << 7;
     private final static int heightChanged = 1 << 8;
@@ -187,9 +241,16 @@
 
     /**
      * Paint one List cell: compute the relevant state, get the "rubber stamp"
-     * cell renderer component, and then use the CellRendererPane to paint it.
-     * Subclasses may want to override this method rather than paint().
+     * cell renderer component, and then use the {@code CellRendererPane} to paint it.
+     * Subclasses may want to override this method rather than {@code paint()}.
      *
+     * @param g an instance of {@code Graphics}
+     * @param row a row
+     * @param rowBounds a bounding rectangle to render to
+     * @param cellRenderer a list of {@code ListCellRenderer}
+     * @param dataModel a list model
+     * @param selModel a selection model
+     * @param leadIndex a lead index
      * @see #paint
      */
     protected void paintCell(
@@ -916,10 +977,11 @@
 
 
     /**
-     * Returns a new instance of BasicListUI.  BasicListUI delegates are
-     * allocated one per JList.
+     * Returns a new instance of {@code BasicListUI}.
+     * {@code BasicListUI} delegates are allocated one per {@code JList}.
      *
-     * @return A new ListUI implementation for the Windows look and feel.
+     * @param list a component
+     * @return a new {@code ListUI} implementation for the Windows look and feel.
      */
     public static ComponentUI createUI(JComponent list) {
         return new BasicListUI();
@@ -1046,7 +1108,8 @@
     /**
      * Returns the height of the specified row based on the current layout.
      *
-     * @return The specified row height or -1 if row isn't valid.
+     * @param row a row
+     * @return the specified row height or -1 if row isn't valid
      * @see #convertYToRow
      * @see #convertRowToY
      * @see #updateLayoutState
@@ -1058,11 +1121,12 @@
 
 
     /**
-     * Convert the JList relative coordinate to the row that contains it,
-     * based on the current layout.  If y0 doesn't fall within any row,
+     * Convert the {@code JList} relative coordinate to the row that contains it,
+     * based on the current layout. If {@code y0} doesn't fall within any row,
      * return -1.
      *
-     * @return The row that contains y0, or -1.
+     * @param y0 a relative Y coordinate
+     * @return the row that contains y0, or -1
      * @see #getRowHeight
      * @see #updateLayoutState
      */
@@ -1073,10 +1137,11 @@
 
 
     /**
-     * Return the JList relative Y coordinate of the origin of the specified
+     * Return the {@code JList} relative Y coordinate of the origin of the specified
      * row or -1 if row isn't valid.
      *
-     * @return The Y coordinate of the origin of row, or -1.
+     * @param row a row
+     * @return the Y coordinate of the origin of row, or -1
      * @see #getRowHeight
      * @see #updateLayoutState
      */
@@ -1535,10 +1600,10 @@
 
 
     /**
-     * Creates a delegate that implements MouseInputListener.
-     * The delegate is added to the corresponding java.awt.Component listener
-     * lists at installUI() time. Subclasses can override this method to return
-     * a custom MouseInputListener, e.g.
+     * Creates a delegate that implements {@code MouseInputListener}.
+     * The delegate is added to the corresponding {@code java.awt.Component} listener
+     * lists at {@code installUI()} time. Subclasses can override this method to return
+     * a custom {@code MouseInputListener}, e.g.
      * <pre>
      * class MyListUI extends BasicListUI {
      *    protected MouseInputListener <b>createMouseInputListener</b>() {
@@ -1553,6 +1618,7 @@
      * }
      * </pre>
      *
+     * @return an instance of {@code MouseInputListener}
      * @see MouseInputHandler
      * @see #installUI
      */
@@ -1566,6 +1632,9 @@
      */
     public class FocusHandler implements FocusListener
     {
+        /**
+         * Repaints focused cells.
+         */
         protected void repaintCellFocus()
         {
             getHandler().repaintCellFocus();
@@ -1584,6 +1653,11 @@
         }
     }
 
+    /**
+     * Returns an instance of {@code FocusListener}.
+     *
+     * @return an instance of {@code FocusListener}
+     */
     protected FocusListener createFocusListener() {
         return getHandler();
     }
@@ -1617,9 +1691,9 @@
 
 
     /**
-     * Creates an instance of ListSelectionHandler that's added to
-     * the JLists by selectionModel as needed.  Subclasses can override
-     * this method to return a custom ListSelectionListener, e.g.
+     * Creates an instance of {@code ListSelectionHandler} that's added to
+     * the {@code JLists} by selectionModel as needed.  Subclasses can override
+     * this method to return a custom {@code ListSelectionListener}, e.g.
      * <pre>
      * class MyListUI extends BasicListUI {
      *    protected ListSelectionListener <b>createListSelectionListener</b>() {
@@ -1634,6 +1708,7 @@
      * }
      * </pre>
      *
+     * @return an instance of {@code ListSelectionHandler}
      * @see ListSelectionHandler
      * @see #installUI
      */
@@ -1649,8 +1724,8 @@
 
 
     /**
-     * The ListDataListener that's added to the JLists model at
-     * installUI time, and whenever the JList.model property changes.
+     * The {@code ListDataListener} that's added to the {@code JLists} model at
+     * {@code installUI time}, and whenever the JList.model property changes.
      * <p>
      * <strong>Warning:</strong>
      * Serialized objects of this class will not be compatible with
@@ -1687,9 +1762,9 @@
 
 
     /**
-     * Creates an instance of ListDataListener that's added to
-     * the JLists by model as needed.  Subclasses can override
-     * this method to return a custom ListDataListener, e.g.
+     * Creates an instance of {@code ListDataListener} that's added to
+     * the {@code JLists} by model as needed. Subclasses can override
+     * this method to return a custom {@code ListDataListener}, e.g.
      * <pre>
      * class MyListUI extends BasicListUI {
      *    protected ListDataListener <b>createListDataListener</b>() {
@@ -1704,6 +1779,7 @@
      * }
      * </pre>
      *
+     * @return an instance of {@code ListDataListener}
      * @see ListDataListener
      * @see JList#getModel
      * @see #installUI
@@ -1744,9 +1820,9 @@
 
 
     /**
-     * Creates an instance of PropertyChangeHandler that's added to
-     * the JList by installUI().  Subclasses can override this method
-     * to return a custom PropertyChangeListener, e.g.
+     * Creates an instance of {@code PropertyChangeHandler} that's added to
+     * the {@code JList} by {@code installUI()}. Subclasses can override this method
+     * to return a custom {@code PropertyChangeListener}, e.g.
      * <pre>
      * class MyListUI extends BasicListUI {
      *    protected PropertyChangeListener <b>createPropertyChangeListener</b>() {
@@ -1763,6 +1839,7 @@
      * }
      * </pre>
      *
+     * @return an instance of {@code PropertyChangeHandler}
      * @see PropertyChangeListener
      * @see #installUI
      */
--- a/src/share/classes/javax/swing/plaf/basic/BasicMenuItemUI.java	Thu Jul 10 15:08:50 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/basic/BasicMenuItemUI.java	Thu Jul 10 17:20:56 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
@@ -47,11 +47,29 @@
  */
 public class BasicMenuItemUI extends MenuItemUI
 {
+    /**
+     * The instance of {@code JMenuItem}.
+     */
     protected JMenuItem menuItem = null;
+    /**
+     * The color of the selection background.
+     */
     protected Color selectionBackground;
+    /**
+     * The color of the selection foreground.
+     */
     protected Color selectionForeground;
+    /**
+     * The color of the disabled foreground.
+     */
     protected Color disabledForeground;
+    /**
+     * The color of the accelerator foreground.
+     */
     protected Color acceleratorForeground;
+    /**
+     * The color of the accelerator selection.
+     */
     protected Color acceleratorSelectionForeground;
 
     /**
@@ -60,18 +78,33 @@
      */
     protected String acceleratorDelimiter;
 
+    /**
+     * The gap between the text and the icon.
+     */
     protected int defaultTextIconGap;
+    /**
+     * The accelerator font.
+     */
     protected Font acceleratorFont;
 
+    /**
+     * The instance of {@code MouseInputListener}.
+     */
     protected MouseInputListener mouseInputListener;
+    /**
+     * The instance of {@code MenuDragMouseListener}.
+     */
     protected MenuDragMouseListener menuDragMouseListener;
+    /**
+     * The instance of {@code MenuKeyListener}.
+     */
     protected MenuKeyListener menuKeyListener;
     /**
-     * <code>PropertyChangeListener</code> returned from
-     * <code>createPropertyChangeListener</code>. You should not
+     * {@code PropertyChangeListener} returned from
+     * {@code createPropertyChangeListener}. You should not
      * need to access this field, rather if you want to customize the
-     * <code>PropertyChangeListener</code> override
-     * <code>createPropertyChangeListener</code>.
+     * {@code PropertyChangeListener} override
+     * {@code createPropertyChangeListener}.
      *
      * @since 1.6
      * @see #createPropertyChangeListener
@@ -79,10 +112,17 @@
     protected PropertyChangeListener propertyChangeListener;
     // BasicMenuUI also uses this.
     Handler handler;
-
+    /**
+     * The arrow icon.
+     */
     protected Icon arrowIcon = null;
+    /**
+     * The check icon.
+     */
     protected Icon checkIcon = null;
-
+    /**
+     * The value represents if the old border is painted.
+     */
     protected boolean oldBorderPainted;
 
     /* diagnostic aids -- should be false for production builds. */
@@ -97,6 +137,12 @@
         BasicLookAndFeel.installAudioActionMap(map);
     }
 
+    /**
+     * Returns a new instance of {@code BasicMenuItemUI}.
+     *
+     * @param c a component
+     * @return a new instance of {@code BasicMenuItemUI}
+     */
     public static ComponentUI createUI(JComponent c) {
         return new BasicMenuItemUI();
     }
@@ -110,7 +156,9 @@
         installKeyboardActions();
     }
 
-
+    /**
+     * Installs default properties.
+     */
     protected void installDefaults() {
         String prefix = getPropertyPrefix();
 
@@ -202,16 +250,26 @@
     }
 
     /**
+     *
+     * @param menuItem a menu item
      * @since 1.3
      */
     protected void installComponents(JMenuItem menuItem){
         BasicHTML.updateRenderer(menuItem, menuItem.getText());
     }
 
+    /**
+     * Returns a property prefix.
+     *
+     * @return a property prefix
+     */
     protected String getPropertyPrefix() {
         return "MenuItem";
     }
 
+    /**
+     * Registers listeners.
+     */
     protected void installListeners() {
         if ((mouseInputListener = createMouseInputListener(menuItem)) != null) {
             menuItem.addMouseListener(mouseInputListener);
@@ -228,6 +286,9 @@
         }
     }
 
+    /**
+     * Registers keyboard action.
+     */
     protected void installKeyboardActions() {
         installLazyActionMap();
         updateAcceleratorBinding();
@@ -248,7 +309,9 @@
         menuItem = null;
     }
 
-
+    /**
+     * Uninstalls default properties.
+     */
     protected void uninstallDefaults() {
         LookAndFeel.uninstallBorder(menuItem);
         LookAndFeel.installProperty(menuItem, "borderPainted", oldBorderPainted);
@@ -261,12 +324,18 @@
     }
 
     /**
+     * Unregisters components.
+     *
+     * @param menuItem a menu item
      * @since 1.3
      */
     protected void uninstallComponents(JMenuItem menuItem){
         BasicHTML.updateRenderer(menuItem, "");
     }
 
+    /**
+     * Unregisters listeners.
+     */
     protected void uninstallListeners() {
         if (mouseInputListener != null) {
             menuItem.removeMouseListener(mouseInputListener);
@@ -289,30 +358,52 @@
         handler = null;
     }
 
+    /**
+     * Unregisters keyboard actions.
+     */
     protected void uninstallKeyboardActions() {
         SwingUtilities.replaceUIActionMap(menuItem, null);
         SwingUtilities.replaceUIInputMap(menuItem, JComponent.
                                          WHEN_IN_FOCUSED_WINDOW, null);
     }
 
+    /**
+     * Returns an instance of {@code MouseInputListener}.
+     *
+     * @param c a component
+     * @return an instance of {@code MouseInputListener}
+     */
     protected MouseInputListener createMouseInputListener(JComponent c) {
         return getHandler();
     }
 
+    /**
+     * Returns an instance of {@code MenuDragMouseListener}.
+     *
+     * @param c a component
+     * @return an instance of {@code MenuDragMouseListener}
+     */
     protected MenuDragMouseListener createMenuDragMouseListener(JComponent c) {
         return getHandler();
     }
 
+    /**
+     * Returns an instance of {@code MenuKeyListener}.
+     *
+     * @param c a component
+     * @return an instance of {@code MenuKeyListener}
+     */
     protected MenuKeyListener createMenuKeyListener(JComponent c) {
         return null;
     }
 
     /**
-     * Creates a <code>PropertyChangeListener</code> which will be added to
+     * Creates a {@code PropertyChangeListener} which will be added to
      * the menu item.
      * If this method returns null then it will not be added to the menu item.
      *
-     * @return an instance of a <code>PropertyChangeListener</code> or null
+     * @param c a component
+     * @return an instance of a {@code PropertyChangeListener} or null
      * @since 1.6
      */
     protected PropertyChangeListener
@@ -380,6 +471,15 @@
         return d;
     }
 
+    /**
+     * Returns the preferred size of a menu item.
+     *
+     * @param c a component
+     * @param checkIcon a check icon
+     * @param arrowIcon an arrow icon
+     * @param defaultTextIconGap a gap between a text and an icon
+     * @return the preferred size of a menu item
+     */
     protected Dimension getPreferredMenuItemSize(JComponent c,
                                                  Icon checkIcon,
                                                  Icon arrowIcon,
@@ -477,6 +577,17 @@
                       defaultTextIconGap);
     }
 
+    /**
+     * Paints a menu item.
+     *
+     * @param g an instance of {@code Graphics}
+     * @param c a component
+     * @param checkIcon a check icon
+     * @param arrowIcon an arrow icon
+     * @param background a background color
+     * @param foreground a foreground color
+     * @param defaultTextIconGap a gap between a text and an icon
+     */
     protected void paintMenuItem(Graphics g, JComponent c,
                                      Icon checkIcon, Icon arrowIcon,
                                      Color background, Color foreground,
@@ -701,6 +812,11 @@
         }
     }
 
+    /**
+     * Returns a menu element path.
+     *
+     * @return a menu element path
+     */
     public MenuElement[] getPath() {
         MenuSelectionManager m = MenuSelectionManager.defaultManager();
         MenuElement oldPath[] = m.getSelectedPath();
--- a/src/share/classes/javax/swing/plaf/basic/BasicProgressBarUI.java	Thu Jul 10 15:08:50 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/basic/BasicProgressBarUI.java	Thu Jul 10 17:20:56 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
@@ -53,7 +53,13 @@
 
     private Animator animator;
 
+    /**
+     * The instance of {@code JProgressBar}.
+     */
     protected JProgressBar progressBar;
+    /**
+     * The instance of {@code ChangeListener}.
+     */
     protected ChangeListener changeListener;
     private Handler handler;
 
@@ -127,7 +133,12 @@
 
     private int maxPosition = 0; //maximum X (horiz) or Y box location
 
-
+    /**
+     * Returns a new instance of {@code BasicProgressBarUI}.
+     *
+     * @param x a component
+     * @return a new instance of {@code BasicProgressBarUI}
+     */
     public static ComponentUI createUI(JComponent x) {
         return new BasicProgressBarUI();
     }
@@ -150,6 +161,9 @@
         progressBar = null;
     }
 
+    /**
+     * Installs default properties.
+     */
     protected void installDefaults() {
         LookAndFeel.installProperty(progressBar, "opaque", Boolean.TRUE);
         LookAndFeel.installBorder(progressBar,"ProgressBar.border");
@@ -164,10 +178,16 @@
         selectionBackground = UIManager.getColor("ProgressBar.selectionBackground");
     }
 
+    /**
+     * Unintalls default properties.
+     */
     protected void uninstallDefaults() {
         LookAndFeel.uninstallBorder(progressBar);
     }
 
+    /**
+     * Registers listeners.
+     */
     protected void installListeners() {
         //Listen for changes in the progress bar's data.
         changeListener = getHandler();
@@ -291,6 +311,11 @@
     // protected void installKeyboardActions()
     // protected void uninstallKeyboardActions()
 
+    /**
+     * Returns preferred size of the horizontal {@code JProgressBar}.
+     *
+     * @return preferred size of the horizontal {@code JProgressBar}
+     */
     protected Dimension getPreferredInnerHorizontal() {
         Dimension horizDim = (Dimension)DefaultLookup.get(progressBar, this,
             "ProgressBar.horizontalSize");
@@ -300,6 +325,11 @@
         return horizDim;
     }
 
+    /**
+     * Returns preferred size of the vertical {@code JProgressBar}.
+     *
+     * @return preferred size of the vertical {@code JProgressBar}
+     */
     protected Dimension getPreferredInnerVertical() {
         Dimension vertDim = (Dimension)DefaultLookup.get(progressBar, this,
             "ProgressBar.verticalSize");
@@ -312,6 +342,8 @@
     /**
      * The "selectionForeground" is the color of the text when it is painted
      * over a filled area of the progress bar.
+     *
+     * @return the color of the selected foreground
      */
     protected Color getSelectionForeground() {
         return selectionForeground;
@@ -320,6 +352,8 @@
     /**
      * The "selectionBackground" is the color of the text when it is painted
      * over an unfilled area of the progress bar.
+     *
+     * @return the color of the selected background
      */
     protected Color getSelectionBackground() {
         return selectionBackground;
@@ -352,6 +386,11 @@
         }
     }
 
+    /**
+     * Sets the cell length.
+     *
+     * @param cellLen a new cell length
+     */
     protected void setCellLength(int cellLen) {
         this.cellLength = cellLen;
     }
@@ -374,6 +413,11 @@
         }
     }
 
+    /**
+     * Sets the cell spacing.
+     *
+     * @param cellSpace a new cell spacing
+     */
     protected void setCellSpacing(int cellSpace) {
         this.cellSpacing = cellSpace;
     }
@@ -384,6 +428,11 @@
      * operation so it was abstracted out. It assumes that your progress bar
      * is linear. That is, if you are making a circular progress indicator,
      * you will want to override this method.
+     *
+     * @param b insets
+     * @param width a width
+     * @param height a height
+     * @return the amount of the progress bar that should be filled
      */
     protected int getAmountFull(Insets b, int width, int height) {
         int amountFull = 0;
@@ -577,6 +626,8 @@
      * Override this if you are making another kind of
      * progress bar.
      *
+     * @param g an instance of {@code Graphics}
+     * @param c a component
      * @see #paintDeterminate
      *
      * @since 1.4
@@ -628,6 +679,8 @@
      * Naturally, override this if you are making a circular or
      * semi-circular progress bar.
      *
+     * @param g an instance of {@code Graphics}
+     * @param c a component
      * @see #paintIndeterminate
      *
      * @since 1.4
@@ -703,7 +756,18 @@
         }
     }
 
-
+    /**
+     * Paints the progress string.
+     *
+     * @param g an instance of {@code Graphics}
+     * @param x X location of bounding box
+     * @param y Y location of bounding box
+     * @param width width of bounding box
+     * @param height height of bounding box
+     * @param amountFull size of the fill region, either width or height
+     *        depending upon orientation.
+     * @param b Insets of the progress bar.
+     */
     protected void paintString(Graphics g, int x, int y,
                                int width, int height,
                                int amountFull, Insets b) {
@@ -793,6 +857,14 @@
      * bar (in both x and y). Override this if you want to right,
      * left, top, or bottom align the progress string or if you need
      * to nudge it around for any reason.
+     *
+     * @param g an instance of {@code Graphics}
+     * @param progressString a text
+     * @param x an X coordinate
+     * @param y an Y coordinate
+     * @param width a width
+     * @param height a height
+     * @return the place where the progress string will be painted
      */
     protected Point getStringPlacement(Graphics g, String progressString,
                                        int x,int y,int width,int height) {
@@ -894,6 +966,7 @@
     /**
      * Gets the index of the current animation frame.
      *
+     * @return the index of the current animation frame
      * @since 1.4
      */
     protected int getAnimationIndex() {
--- a/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneUI.java	Thu Jul 10 15:08:50 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneUI.java	Thu Jul 10 17:20:56 2014 +0400
@@ -286,7 +286,10 @@
 
 
     /**
-     * Creates a new BasicSplitPaneUI instance
+     * Creates a new instance of {@code BasicSplitPaneUI}.
+     *
+     * @param x a component
+     * @return a new instance of {@code BasicSplitPaneUI}
      */
     public static ComponentUI createUI(JComponent x) {
         return new BasicSplitPaneUI();
@@ -503,7 +506,9 @@
 
 
     /**
-     * Creates a PropertyChangeListener for the JSplitPane UI.
+     * Creates a {@code PropertyChangeListener} for the {@code JSplitPane} UI.
+     *
+     * @return an instance of {@code PropertyChangeListener}
      */
     protected PropertyChangeListener createPropertyChangeListener() {
         return getHandler();
@@ -518,7 +523,9 @@
 
 
     /**
-     * Creates a FocusListener for the JSplitPane UI.
+     * Creates a {@code FocusListener} for the {@code JSplitPane} UI.
+     *
+     * @return an instance of {@code FocusListener}
      */
     protected FocusListener createFocusListener() {
         return getHandler();
@@ -526,16 +533,17 @@
 
 
     /**
-     * As of Java 2 platform v1.3 this method is no
-     * longer used. Subclassers previously using this method should
-     * instead create an Action wrapping the ActionListener, and register
-     * that Action by overriding <code>installKeyboardActions</code> and
-     * placing the Action in the SplitPane's ActionMap. Please refer to
-     * the key bindings specification for further details.
+     * As of Java 2 platform v1.3 this method is no longer used.
+     * Subclassers previously using this method should instead create
+     * an {@code Action} wrapping the {@code ActionListener}, and register
+     * that {@code Action} by overriding {@code installKeyboardActions}
+     * and placing the {@code Action} in the {@code SplitPane's ActionMap}.
+     * Please refer to the key bindings specification for further details.
      * <p>
-     * Creates a ActionListener for the JSplitPane UI that listens for
-     * specific key presses.
+     * Creates an {@code ActionListener} for the {@code JSplitPane} UI that
+     * listens for specific key presses.
      *
+     * @return an instance of {@code ActionListener}
      * @deprecated As of Java 2 platform v1.3.
      */
     @Deprecated
@@ -545,16 +553,17 @@
 
 
     /**
-     * As of Java 2 platform v1.3 this method is no
-     * longer used. Subclassers previously using this method should
-     * instead create an Action wrapping the ActionListener, and register
-     * that Action by overriding <code>installKeyboardActions</code> and
-     * placing the Action in the SplitPane's ActionMap. Please refer to
-     * the key bindings specification for further details.
+     * As of Java 2 platform v1.3 this method is no longer used.
+     * Subclassers previously using this method should instead create
+     * an {@code Action} wrapping the {@code ActionListener}, and register
+     * that {@code Action} by overriding {@code installKeyboardActions}
+     * and placing the {@code Action} in the {@code SplitPane's ActionMap}.
+     * Please refer to the key bindings specification for further details.
      * <p>
-     * Creates a ActionListener for the JSplitPane UI that listens for
-     * specific key presses.
+     * Creates an {@code ActionListener} for the {@code JSplitPane} UI that
+     * listens for specific key presses.
      *
+     * @return an instance of {@code ActionListener}
      * @deprecated As of Java 2 platform v1.3.
      */
     @Deprecated
@@ -564,16 +573,17 @@
 
 
     /**
-     * As of Java 2 platform v1.3 this method is no
-     * longer used. Subclassers previously using this method should
-     * instead create an Action wrapping the ActionListener, and register
-     * that Action by overriding <code>installKeyboardActions</code> and
-     * placing the Action in the SplitPane's ActionMap. Please refer to
-     * the key bindings specification for further details.
+     * As of Java 2 platform v1.3 this method is no longer used.
+     * Subclassers previously using this method should instead create
+     * an {@code Action} wrapping the {@code ActionListener}, and register
+     * that {@code Action} by overriding {@code installKeyboardActions}
+     * and placing the {@code Action} in the {@code SplitPane's ActionMap}.
+     * Please refer to the key bindings specification for further details.
      * <p>
-     * Creates a ActionListener for the JSplitPane UI that listens for
-     * specific key presses.
+     * Creates an {@code ActionListener} for the {@code JSplitPane} UI that
+     * listens for specific key presses.
      *
+     * @return an instance of {@code ActionListener}
      * @deprecated As of Java 2 platform v1.3.
      */
     @Deprecated
@@ -583,16 +593,17 @@
 
 
     /**
-     * As of Java 2 platform v1.3 this method is no
-     * longer used. Subclassers previously using this method should
-     * instead create an Action wrapping the ActionListener, and register
-     * that Action by overriding <code>installKeyboardActions</code> and
-     * placing the Action in the SplitPane's ActionMap. Please refer to
-     * the key bindings specification for further details.
+     * As of Java 2 platform v1.3 this method is no longer used.
+     * Subclassers previously using this method should instead create
+     * an {@code Action} wrapping the {@code ActionListener}, and register
+     * that {@code Action} by overriding {@code installKeyboardActions}
+     * and placing the {@code Action} in the {@code SplitPane's ActionMap}.
+     * Please refer to the key bindings specification for further details.
      * <p>
-     * Creates a ActionListener for the JSplitPane UI that listens for
-     * specific key presses.
+     * Creates an {@code ActionListener} for the {@code JSplitPane} UI that
+     * listens for specific key presses.
      *
+     * @return an instance of {@code ActionListener}
      * @deprecated As of Java 2 platform v1.3.
      */
     @Deprecated
@@ -602,16 +613,17 @@
 
 
     /**
-     * As of Java 2 platform v1.3 this method is no
-     * longer used. Subclassers previously using this method should
-     * instead create an Action wrapping the ActionListener, and register
-     * that Action by overriding <code>installKeyboardActions</code> and
-     * placing the Action in the SplitPane's ActionMap. Please refer to
-     * the key bindings specification for further details.
+     * As of Java 2 platform v1.3 this method is no longer used.
+     * Subclassers previously using this method should instead create
+     * an {@code Action} wrapping the {@code ActionListener}, and register
+     * that {@code Action} by overriding {@code installKeyboardActions}
+     * and placing the {@code Action} in the {@code SplitPane's ActionMap}.
+     * Please refer to the key bindings specification for further details.
      * <p>
-     * Creates a ActionListener for the JSplitPane UI that listens for
-     * specific key presses.
+     * Creates an {@code ActionListener} for the {@code JSplitPane} UI that
+     * listens for specific key presses.
      *
+     * @return an instance of {@code ActionListener}
      * @deprecated As of Java 2 platform v1.3.
      */
     @Deprecated
@@ -621,7 +633,9 @@
 
 
     /**
-     * Returns the orientation for the JSplitPane.
+     * Returns the orientation for the {@code JSplitPane}.
+     *
+     * @return the orientation
      */
     public int getOrientation() {
         return orientation;
@@ -629,7 +643,9 @@
 
 
     /**
-     * Set the orientation for the JSplitPane.
+     * Set the orientation for the {@code JSplitPane}.
+     *
+     * @param orientation the orientation
      */
     public void setOrientation(int orientation) {
         this.orientation = orientation;
@@ -637,7 +653,9 @@
 
 
     /**
-     * Determines whether the JSplitPane is set to use a continuous layout.
+     * Determines whether the {@code JSplitPane} is set to use a continuous layout.
+     *
+     * @return {@code true} if a continuous layout is set
      */
     public boolean isContinuousLayout() {
         return continuousLayout;
@@ -646,6 +664,8 @@
 
     /**
      * Turn continuous layout on/off.
+     *
+     * @param b if {@code true} the continuous layout turns on
      */
     public void setContinuousLayout(boolean b) {
         continuousLayout = b;
@@ -653,7 +673,9 @@
 
 
     /**
-     * Returns the last drag location of the JSplitPane.
+     * Returns the last drag location of the {@code JSplitPane}.
+     *
+     * @return the last drag location
      */
     public int getLastDragLocation() {
         return lastDragLocation;
@@ -661,7 +683,9 @@
 
 
     /**
-     * Set the last drag location of the JSplitPane.
+     * Set the last drag location of the {@code JSplitPane}.
+     *
+     * @param l the drag location
      */
     public void setLastDragLocation(int l) {
         lastDragLocation = l;
@@ -819,6 +843,8 @@
 
     /**
      * Returns the divider between the top Components.
+     *
+     * @return the divider between the top Components
      */
     public BasicSplitPaneDivider getDivider() {
         return divider;
@@ -828,6 +854,8 @@
     /**
      * Returns the default non continuous layout divider, which is an
      * instance of {@code Canvas} that fills in the background with dark gray.
+     *
+     * @return the default non continuous layout divider
      */
     @SuppressWarnings("serial") // anonymous class
     protected Component createDefaultNonContinuousLayoutDivider() {
@@ -849,10 +877,12 @@
 
 
     /**
-     * Sets the divider to use when the splitPane is configured to
+     * Sets the divider to use when the {@code JSplitPane} is configured to
      * not continuously layout. This divider will only be used during a
      * dragging session. It is recommended that the passed in component
      * be a heavy weight.
+     *
+     * @param newDivider the new divider
      */
     protected void setNonContinuousLayoutDivider(Component newDivider) {
         setNonContinuousLayoutDivider(newDivider, true);
@@ -861,6 +891,9 @@
 
     /**
      * Sets the divider to use.
+     *
+     * @param newDivider the new divider
+     * @param rememberSizes if {@code true} the pane size is remembered
      */
     protected void setNonContinuousLayoutDivider(Component newDivider,
         boolean rememberSizes) {
@@ -903,9 +936,11 @@
 
 
     /**
-     * Returns the divider to use when the splitPane is configured to
+     * Returns the divider to use when the {@code JSplitPane} is configured to
      * not continuously layout. This divider will only be used during a
      * dragging session.
+     *
+     * @return the divider
      */
     public Component getNonContinuousLayoutDivider() {
         return nonContinuousLayoutDivider;
@@ -913,8 +948,10 @@
 
 
     /**
-     * Returns the splitpane this instance is currently contained
+     * Returns the {@code JSplitPane} this instance is currently contained
      * in.
+     *
+     * @return the instance of {@code JSplitPane}
      */
     public JSplitPane getSplitPane() {
         return splitPane;
@@ -923,6 +960,8 @@
 
     /**
      * Creates the default divider.
+     *
+     * @return the default divider
      */
     public BasicSplitPaneDivider createDefaultDivider() {
         return new BasicSplitPaneDivider(this);
@@ -1108,6 +1147,9 @@
     /**
      * Returns the insets. The insets are returned from the border insets
      * of the current border.
+     *
+     * @param jc a component
+     * @return the insets
      */
     public Insets getInsets(JComponent jc) {
         return null;
@@ -1187,8 +1229,10 @@
 
     /**
      * Messaged during a dragging session to move the divider to the
-     * passed in location. If continuousLayout is true the location is
-     * reset and the splitPane validated.
+     * passed in {@code location}. If {@code continuousLayout} is {@code true}
+     * the location is reset and the splitPane validated.
+     *
+     * @param location the location of divider
      */
     protected void dragDividerTo(int location) {
         if(getLastDragLocation() != location) {
@@ -1230,7 +1274,9 @@
 
     /**
      * Messaged to finish the dragging session. If not continuous display
-     * the dividers location will be reset.
+     * the dividers {@code location} will be reset.
+     *
+     * @param location the location of divider
      */
     protected void finishDraggingTo(int location) {
         dragDividerTo(location);
@@ -1259,6 +1305,7 @@
      * <p>
      * Returns the width of one side of the divider border.
      *
+     * @return the width of one side of the divider border
      * @deprecated As of Java 2 platform v1.3, instead set the border on the
      * divider.
      */
@@ -1275,7 +1322,13 @@
     public class BasicHorizontalLayoutManager implements LayoutManager2
     {
         /* left, right, divider. (in this exact order) */
+        /**
+         * The size of components.
+         */
         protected int[]         sizes;
+        /**
+         * The components.
+         */
         protected Component[]   components;
         /** Size of the splitpane the last time laid out. */
         private int             lastSplitPaneSize;
@@ -1596,6 +1649,8 @@
 
         /**
          * Resets the size of the Component at the passed in location.
+         *
+         * @param index the index of a component
          */
         protected void resetSizeAt(int index) {
             sizes[index] = 0;
@@ -1604,7 +1659,9 @@
 
 
         /**
-         * Sets the sizes to <code>newSizes</code>.
+         * Sets the sizes to {@code newSizes}.
+         *
+         * @param newSizes the new sizes
          */
         protected void setSizes(int[] newSizes) {
             System.arraycopy(newSizes, 0, sizes, 0, 3);
@@ -1613,6 +1670,8 @@
 
         /**
          * Returns the sizes of the components.
+         *
+         * @return the sizes of the components
          */
         protected int[] getSizes() {
             int[]         retSizes = new int[3];
@@ -1624,6 +1683,9 @@
 
         /**
          * Returns the width of the passed in Components preferred size.
+         *
+         * @param c a component
+         * @return the preferred width of the component
          */
         protected int getPreferredSizeOfComponent(Component c) {
             return getSizeForPrimaryAxis(c.getPreferredSize());
@@ -1632,6 +1694,9 @@
 
         /**
          * Returns the width of the passed in Components minimum size.
+         *
+         * @param c a component
+         * @return the minimum width of the component
          */
         int getMinimumSizeOfComponent(Component c) {
             return getSizeForPrimaryAxis(c.getMinimumSize());
@@ -1640,6 +1705,9 @@
 
         /**
          * Returns the width of the passed in component.
+         *
+         * @param c a component
+         * @return the width of the component
          */
         protected int getSizeOfComponent(Component c) {
             return getSizeForPrimaryAxis(c.getSize());
@@ -1648,7 +1716,11 @@
 
         /**
          * Returns the available width based on the container size and
-         * Insets.
+         * {@code Insets}.
+         *
+         * @param containerSize a container size
+         * @param insets an insets
+         * @return the available width
          */
         protected int getAvailableSize(Dimension containerSize,
                                        Insets insets) {
@@ -1661,8 +1733,11 @@
 
 
         /**
-         * Returns the left inset, unless the Insets are null in which case
+         * Returns the left inset, unless the {@code Insets} are null in which case
          * 0 is returned.
+         *
+         * @param insets the insets
+         * @return the left inset
          */
         protected int getInitialLocation(Insets insets) {
             if(insets != null)
@@ -1672,9 +1747,15 @@
 
 
         /**
-         * Sets the width of the component c to be size, placing its
-         * x location at location, y to the insets.top and height
-         * to the containersize.height less the top and bottom insets.
+         * Sets the width of the component {@code c} to be {@code size}, placing its
+         * x location at {@code location}, y to the {@code insets.top} and height
+         * to the {@code containerSize.height} less the top and bottom insets.
+         *
+         * @param c a component
+         * @param size a new width
+         * @param location a new X coordinate
+         * @param insets an insets
+         * @param containerSize a container size
          */
         protected void setComponentToSize(Component c, int size,
                                           int location, Insets insets,
@@ -2021,6 +2102,9 @@
     public class BasicVerticalLayoutManager extends
             BasicHorizontalLayoutManager
     {
+        /**
+         * Constructs a new instance of {@code BasicVerticalLayoutManager}.
+         */
         public BasicVerticalLayoutManager() {
             super(1);
         }