changeset 10398:b7d9f25bd883

8049870: Fix doclint warnings from javax.swing.plaf.basic package, 4 of 7 Reviewed-by: pchelko
author aeremeev
date Fri, 11 Jul 2014 16:44:11 +0400
parents 8a286e644c92
children 94f03bb92f78
files src/share/classes/javax/swing/plaf/basic/BasicInternalFrameTitlePane.java src/share/classes/javax/swing/plaf/basic/BasicOptionPaneUI.java src/share/classes/javax/swing/plaf/basic/BasicToolBarUI.java
diffstat 3 files changed, 572 insertions(+), 39 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/javax/swing/plaf/basic/BasicInternalFrameTitlePane.java	Fri Jul 11 13:32:12 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/basic/BasicInternalFrameTitlePane.java	Fri Jul 11 16:44:11 2014 +0400
@@ -60,44 +60,125 @@
 @SuppressWarnings("serial") // Same-version serialization only
 public class BasicInternalFrameTitlePane extends JComponent
 {
+    /**
+     * The instance of {@code JMenuBar}.
+     */
     protected JMenuBar menuBar;
+    /**
+     * The iconify button.
+     */
     protected JButton iconButton;
+    /**
+     * The maximize button.
+     */
     protected JButton maxButton;
+    /**
+     * The close button.
+     */
     protected JButton closeButton;
 
+    /**
+     * The instance of {@code JMenu}.
+     */
     protected JMenu windowMenu;
+    /**
+     * The instance of {@code JInternalFrame}.
+     */
     protected JInternalFrame frame;
 
+    /**
+     * The color of a selected title.
+     */
     protected Color selectedTitleColor;
+    /**
+     * The color of a selected text.
+     */
     protected Color selectedTextColor;
+    /**
+     * The color of a not selected title.
+     */
     protected Color notSelectedTitleColor;
+    /**
+     * The color of a not selected text.
+     */
     protected Color notSelectedTextColor;
 
+    /**
+     * The maximize icon.
+     */
     protected Icon maxIcon;
+    /**
+     * The minimize icon.
+     */
     protected Icon minIcon;
+    /**
+     * The iconify icon.
+     */
     protected Icon iconIcon;
+    /**
+     * The close icon.
+     */
     protected Icon closeIcon;
 
+    /**
+     * The instance of a {@code PropertyChangeListener}.
+     */
     protected PropertyChangeListener propertyChangeListener;
 
+    /**
+     * The instance of a {@code CloseAction}.
+     */
     protected Action closeAction;
+    /**
+     * The instance of a {@code MaximizeAction}.
+     */
     protected Action maximizeAction;
+    /**
+     * The instance of an {@code IconifyAction}.
+     */
     protected Action iconifyAction;
+    /**
+     * The instance of a {@code RestoreAction}.
+     */
     protected Action restoreAction;
+    /**
+     * The instance of a {@code MoveAction}.
+     */
     protected Action moveAction;
+    /**
+     * The instance of a {@code SizeAction}.
+     */
     protected Action sizeAction;
 
     // These constants are not used in JDK code
+    /**
+     * The close button text property.
+     */
     protected static final String CLOSE_CMD =
         UIManager.getString("InternalFrameTitlePane.closeButtonText");
+    /**
+     * The minimize button text property.
+     */
     protected static final String ICONIFY_CMD =
         UIManager.getString("InternalFrameTitlePane.minimizeButtonText");
+    /**
+     * The restore button text property.
+     */
     protected static final String RESTORE_CMD =
         UIManager.getString("InternalFrameTitlePane.restoreButtonText");
+    /**
+     * The maximize button text property.
+     */
     protected static final String MAXIMIZE_CMD =
         UIManager.getString("InternalFrameTitlePane.maximizeButtonText");
+    /**
+     * The move button text property.
+     */
     protected static final String MOVE_CMD =
         UIManager.getString("InternalFrameTitlePane.moveButtonText");
+    /**
+     * The size button text property.
+     */
     protected static final String SIZE_CMD =
         UIManager.getString("InternalFrameTitlePane.sizeButtonText");
 
@@ -107,11 +188,19 @@
     private String maxButtonToolTip;
     private Handler handler;
 
+    /**
+     * Constructs a new instance of {@code BasicInternalFrameTitlePane}.
+     *
+     * @param f an instance of {@code JInternalFrame}
+     */
     public BasicInternalFrameTitlePane(JInternalFrame f) {
         frame = f;
         installTitlePane();
     }
 
+    /**
+     * Installs the title pane.
+     */
     protected void installTitlePane() {
         installDefaults();
         installListeners();
@@ -128,6 +217,9 @@
 
     }
 
+    /**
+     * Adds subcomponents.
+     */
     protected void addSubComponents() {
         add(menuBar);
         add(iconButton);
@@ -135,6 +227,9 @@
         add(closeButton);
     }
 
+    /**
+     * Creates actions.
+     */
     protected void createActions() {
         maximizeAction = new MaximizeAction();
         iconifyAction = new IconifyAction();
@@ -151,6 +246,9 @@
         return map;
     }
 
+    /**
+     * Registers listeners.
+     */
     protected void installListeners() {
         if( propertyChangeListener == null ) {
             propertyChangeListener = createPropertyChangeListener();
@@ -158,11 +256,17 @@
         frame.addPropertyChangeListener(propertyChangeListener);
     }
 
+    /**
+     * Unregisters listeners.
+     */
     protected void uninstallListeners() {
         frame.removePropertyChangeListener(propertyChangeListener);
         handler = null;
     }
 
+    /**
+     * Installs default properties.
+     */
     protected void installDefaults() {
         maxIcon = UIManager.getIcon("InternalFrame.maximizeIcon");
         minIcon = UIManager.getIcon("InternalFrame.minimizeIcon");
@@ -184,10 +288,15 @@
                 UIManager.getString("InternalFrame.maxButtonToolTip");
     }
 
-
+    /**
+     * Uninstalls default properties.
+     */
     protected void uninstallDefaults() {
     }
 
+    /**
+     * Creates buttons.
+     */
     protected void createButtons() {
         iconButton = new NoFocusButton(
                      "InternalFrameTitlePane.iconifyButtonAccessibleName",
@@ -213,6 +322,9 @@
         setButtonIcons();
     }
 
+    /**
+     * Sets the button icons.
+     */
     protected void setButtonIcons() {
         if(frame.isIcon()) {
             if (minIcon != null) {
@@ -261,6 +373,9 @@
         }
     }
 
+    /**
+     * Assembles system menu.
+     */
     protected void assembleSystemMenu() {
         menuBar = createSystemMenuBar();
         windowMenu = createSystemMenu();
@@ -269,6 +384,11 @@
         enableActions();
     }
 
+    /**
+     * Adds system menu items to {@code systemMenu}.
+     *
+     * @param systemMenu an instance of {@code JMenu}
+     */
     protected void addSystemMenuItems(JMenu systemMenu) {
         JMenuItem mi = systemMenu.add(restoreAction);
         mi.setMnemonic(getButtonMnemonic("restore"));
@@ -294,16 +414,29 @@
         }
     }
 
+    /**
+     * Returns a new instance of {@code JMenu}.
+     *
+     * @return a new instance of {@code JMenu}
+     */
     protected JMenu createSystemMenu() {
         return new JMenu("    ");
     }
 
+    /**
+     * Returns a new instance of {@code JMenuBar}.
+     *
+     * @return a new instance of {@code JMenuBar}
+     */
     protected JMenuBar createSystemMenuBar() {
         menuBar = new SystemMenuBar();
         menuBar.setBorderPainted(false);
         return menuBar;
     }
 
+    /**
+     * Shows system menu.
+     */
     protected void showSystemMenu(){
         //      windowMenu.setPopupMenuVisible(true);
       //      windowMenu.setVisible(true);
@@ -367,14 +500,24 @@
         g.fillRect(0, 0, getWidth(), getHeight());
     }
 
+    /**
+     * Returns the title.
+     *
+     * @param text a text
+     * @param fm an instance of {@code FontMetrics}
+     * @param availTextWidth an available text width
+     * @return the title.
+     */
     protected String getTitle(String text, FontMetrics fm, int availTextWidth) {
         return SwingUtilities2.clipStringIfNecessary(
                            frame, fm, text, availTextWidth);
-      }
+    }
 
     /**
      * Post a WINDOW_CLOSING-like event to the frame, so that it can
-     * be treated like a regular Frame.
+     * be treated like a regular {@code Frame}.
+     *
+     * @param frame an instance of {@code JInternalFrame}
      */
     protected void postClosingEvent(JInternalFrame frame) {
         InternalFrameEvent e = new InternalFrameEvent(
@@ -387,7 +530,9 @@
         }
     }
 
-
+    /**
+     * Enables actions.
+     */
     protected void enableActions() {
         restoreAction.setEnabled(frame.isMaximum() || frame.isIcon());
         maximizeAction.setEnabled(
@@ -406,10 +551,20 @@
         return handler;
     }
 
+    /**
+     * Returns an instance of {@code PropertyChangeListener}.
+     *
+     * @return an instance of {@code PropertyChangeListener}
+     */
     protected PropertyChangeListener createPropertyChangeListener() {
         return getHandler();
     }
 
+    /**
+     * Returns a layout manager.
+     *
+     * @return a layout manager
+     */
     protected LayoutManager createLayout() {
         return getHandler();
     }
@@ -606,6 +761,9 @@
      * Instantiate it only within subclasses of <code>Foo</code>.
      */
     public class CloseAction extends AbstractAction {
+        /**
+         * Constructs a new instance of a {@code CloseAction}.
+         */
         public CloseAction() {
             super(UIManager.getString(
                     "InternalFrameTitlePane.closeButtonText"));
@@ -623,6 +781,9 @@
      * Instantiate it only within subclasses of <code>Foo</code>.
      */
     public class MaximizeAction extends AbstractAction {
+        /**
+         * Constructs a new instance of a {@code MaximizeAction}.
+         */
         public MaximizeAction() {
             super(UIManager.getString(
                     "InternalFrameTitlePane.maximizeButtonText"));
@@ -652,6 +813,9 @@
      * Instantiate it only within subclasses of <code>Foo</code>.
      */
     public class IconifyAction extends AbstractAction {
+        /**
+         * Constructs a new instance of an {@code IconifyAction}.
+         */
         public IconifyAction() {
             super(UIManager.getString(
                     "InternalFrameTitlePane.minimizeButtonText"));
@@ -673,6 +837,9 @@
      * Instantiate it only within subclasses of <code>Foo</code>.
      */
     public class RestoreAction extends AbstractAction {
+        /**
+         * Constructs a new instance of a {@code RestoreAction}.
+         */
         public RestoreAction() {
             super(UIManager.getString(
                     "InternalFrameTitlePane.restoreButtonText"));
@@ -700,6 +867,9 @@
      * Instantiate it only within subclasses of <code>Foo</code>.
      */
     public class MoveAction extends AbstractAction {
+        /**
+         * Constructs a new instance of a {@code MoveAction}.
+         */
         public MoveAction() {
             super(UIManager.getString(
                     "InternalFrameTitlePane.moveButtonText"));
@@ -734,6 +904,9 @@
      * Instantiate it only within subclasses of <code>Foo</code>.
      */
     public class SizeAction extends AbstractAction {
+        /**
+         * Constructs a new instance of a {@code SizeAction}.
+         */
         public SizeAction() {
             super(UIManager.getString(
                     "InternalFrameTitlePane.sizeButtonText"));
--- a/src/share/classes/javax/swing/plaf/basic/BasicOptionPaneUI.java	Fri Jul 11 13:32:12 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/basic/BasicOptionPaneUI.java	Fri Jul 11 16:44:11 2014 +0400
@@ -79,17 +79,26 @@
  */
 public class BasicOptionPaneUI extends OptionPaneUI {
 
+    /**
+     * The mininum width of {@code JOptionPane}.
+     */
     public static final int MinimumWidth = 262;
+    /**
+     * The mininum height of {@code JOptionPane}.
+     */
     public static final int MinimumHeight = 90;
 
     private static String newline;
 
     /**
-     * <code>JOptionPane</code> that the receiver is providing the
+     * {@code JOptionPane} that the receiver is providing the
      * look and feel for.
      */
     protected JOptionPane         optionPane;
 
+    /**
+     * The size of {@code JOptionPane}.
+     */
     protected Dimension minimumSize;
 
     /** JComponent provide for input if optionPane.getWantsInput() returns
@@ -103,6 +112,9 @@
      * in either the message or the buttons. */
     protected boolean             hasCustomComponents;
 
+    /**
+     * The instance of {@code PropertyChangeListener}.
+     */
     protected PropertyChangeListener propertyChangeListener;
 
     private Handler handler;
@@ -123,8 +135,10 @@
 
 
     /**
-      * Creates a new BasicOptionPaneUI instance.
-      */
+     * Creates a new {@code BasicOptionPaneUI} instance.
+     *
+     * @return a new {@code BasicOptionPaneUI} instance
+     */
     public static ComponentUI createUI(JComponent x) {
         return new BasicOptionPaneUI();
     }
@@ -155,6 +169,9 @@
         optionPane = null;
     }
 
+    /**
+     * Installs default properties.
+     */
     protected void installDefaults() {
         LookAndFeel.installColorsAndFont(optionPane, "OptionPane.background",
                                          "OptionPane.foreground", "OptionPane.font");
@@ -163,10 +180,16 @@
         LookAndFeel.installProperty(optionPane, "opaque", Boolean.TRUE);
     }
 
+    /**
+     * Uninstalls default properties.
+     */
     protected void uninstallDefaults() {
         LookAndFeel.uninstallBorder(optionPane);
     }
 
+    /**
+     * Registers components.
+     */
     protected void installComponents() {
         optionPane.add(createMessageArea());
 
@@ -178,6 +201,9 @@
         optionPane.applyComponentOrientation(optionPane.getComponentOrientation());
     }
 
+    /**
+     * Unregisters components.
+     */
     protected void uninstallComponents() {
         hasCustomComponents = false;
         inputComponent = null;
@@ -185,16 +211,27 @@
         optionPane.removeAll();
     }
 
+    /**
+     * Returns a layout manager.
+     *
+     * @return a layout manager
+     */
     protected LayoutManager createLayoutManager() {
         return new BoxLayout(optionPane, BoxLayout.Y_AXIS);
     }
 
+    /**
+     * Registers listeners.
+     */
     protected void installListeners() {
         if ((propertyChangeListener = createPropertyChangeListener()) != null) {
             optionPane.addPropertyChangeListener(propertyChangeListener);
         }
     }
 
+    /**
+     * Unregisters listeners.
+     */
     protected void uninstallListeners() {
         if (propertyChangeListener != null) {
             optionPane.removePropertyChangeListener(propertyChangeListener);
@@ -203,6 +240,11 @@
         handler = null;
     }
 
+    /**
+     * Returns an instance of {@code PropertyChangeListener}.
+     *
+     * @return an instance of {@code PropertyChangeListener}
+     */
     protected PropertyChangeListener createPropertyChangeListener() {
         return getHandler();
     }
@@ -214,6 +256,9 @@
         return handler;
     }
 
+    /**
+     * Registers keyboard actions.
+     */
     protected void installKeyboardActions() {
         InputMap map = getInputMap(JComponent.WHEN_IN_FOCUSED_WINDOW);
 
@@ -224,6 +269,9 @@
                                            "OptionPane.actionMap");
     }
 
+    /**
+     * Unregisters keyboard actions.
+     */
     protected void uninstallKeyboardActions() {
         SwingUtilities.replaceUIInputMap(optionPane, JComponent.
                                        WHEN_IN_FOCUSED_WINDOW, null);
@@ -244,6 +292,8 @@
     /**
      * Returns the minimum size the option pane should be. Primarily
      * provided for subclassers wishing to offer a different minimum size.
+     *
+     * @return the minimum size of the option pane
      */
     public Dimension getMinimumOptionPaneSize() {
         if (minimumSize == null) {
@@ -280,9 +330,11 @@
     }
 
     /**
-     * Messaged from installComponents to create a Container containing the
-     * body of the message. The icon is the created by calling
-     * <code>addIcon</code>.
+     * Messaged from {@code installComponents} to create a {@code Container}
+     * containing the body of the message. The icon is the created
+     * by calling {@code addIcon}.
+     *
+     * @return a instance of {@code Container}
      */
     protected Container createMessageArea() {
         JPanel top = new JPanel();
@@ -325,15 +377,21 @@
     }
 
     /**
-     * Creates the appropriate object to represent <code>msg</code> and
-     * places it into <code>container</code>. If <code>msg</code> is an
-     * instance of Component, it is added directly, if it is an Icon,
-     * a JLabel is created to represent it, otherwise a JLabel is
-     * created for the string, if <code>d</code> is an Object[], this
-     * method will be recursively invoked for the children.
-     * <code>internallyCreated</code> is true if Objc is an instance
-     * of Component and was created internally by this method (this is
-     * used to correctly set hasCustomComponents only if !internallyCreated).
+     * Creates the appropriate object to represent {@code msg} and
+     * places it into {@code container}. If {@code msg} is an instance of
+     * {@code Component}, it is added directly, if it is an {@code Icon},
+     * a {@code JLabel} is created to represent it, otherwise a {@code JLabel} is
+     * created for the string, if {@code d} is an Object[], this method
+     * will be recursively invoked for the children. {@code internallyCreated} is
+     * {@code true} if Objc is an instance of {@code Component} and was created
+     * internally by this method (this is used to correctly set
+     * {@code hasCustomComponents} only if {@code internallyCreated} is {@code false}).
+     *
+     * @param container a container
+     * @param cons an instance of {@code GridBagConstraints}
+     * @param msg a message
+     * @param maxll a maximum length
+     * @param internallyCreated {@code true} if the component was internally created
      */
     protected void addMessageComponents(Container container,
                                      GridBagConstraints cons,
@@ -431,8 +489,10 @@
     }
 
     /**
-     * Returns the message to display from the JOptionPane the receiver is
+     * Returns the message to display from the {@code JOptionPane} the receiver is
      * providing the look and feel for.
+     *
+     * @return the message to display
      */
     protected Object getMessage() {
         inputComponent = null;
@@ -514,8 +574,10 @@
 
     /**
      * Creates and adds a JLabel representing the icon returned from
-     * <code>getIcon</code> to <code>top</code>. This is messaged from
-     * <code>createMessageArea</code>
+     * {@code getIcon} to {@code top}. This is messaged from
+     * {@code createMessageArea}.
+     *
+     * @param top a container
      */
     protected void addIcon(Container top) {
         /* Create the icon. */
@@ -531,9 +593,11 @@
     }
 
     /**
-     * Returns the icon from the JOptionPane the receiver is providing
+     * Returns the icon from the {@code JOptionPane} the receiver is providing
      * the look and feel for, or the default icon as returned from
-     * <code>getDefaultIcon</code>.
+     * {@code getDefaultIcon}.
+     *
+     * @return the icon
      */
     protected Icon getIcon() {
         Icon      mIcon = (optionPane == null ? null : optionPane.getIcon());
@@ -545,6 +609,9 @@
 
     /**
      * Returns the icon to use for the passed in type.
+     *
+     * @param messageType a type of message
+     * @return the icon to use for the passed in type
      */
     protected Icon getIconForType(int messageType) {
         if(messageType < 0 || messageType > 3)
@@ -572,14 +639,20 @@
 
     /**
      * Returns the maximum number of characters to place on a line.
+     *
+     * @return the maximum number of characters to place on a line
      */
     protected int getMaxCharactersPerLineCount() {
         return optionPane.getMaxCharactersPerLineCount();
     }
 
-   /**
-     * Recursively creates new JLabel instances to represent <code>d</code>.
-     * Each JLabel instance is added to <code>c</code>.
+    /**
+     * Recursively creates new {@code JLabel} instances to represent {@code d}.
+     * Each {@code JLabel} instance is added to {@code c}.
+     *
+     * @param c a container
+     * @param d a text
+     * @param maxll a maximum length of a text
      */
     protected void burstStringInto(Container c, String d, int maxll) {
         // Primitive line wrapping
@@ -602,13 +675,20 @@
         c.add(label);
     }
 
+    /**
+     * Returns a separator.
+     *
+     * @return a separator
+     */
     protected Container createSeparator() {
         return null;
     }
 
     /**
-     * Creates and returns a Container containing the buttons. The buttons
-     * are created by calling <code>getButtons</code>.
+     * Creates and returns a {@code Container} containing the buttons.
+     * The buttons are created by calling {@code getButtons}.
+     *
+     * @return a {@code Container} containing the buttons
      */
     protected Container createButtonArea() {
         JPanel bottom = new JPanel();
@@ -633,10 +713,14 @@
 
     /**
      * Creates the appropriate object to represent each of the objects in
-     * <code>buttons</code> and adds it to <code>container</code>. This
+     * {@code buttons} and adds it to {@code container}. This
      * differs from addMessageComponents in that it will recurse on
-     * <code>buttons</code> and that if button is not a Component
+     * {@code buttons} and that if button is not a Component
      * it will create an instance of JButton.
+     *
+     * @param container a container
+     * @param buttons an array of buttons
+     * @param initialIndex an initial index
      */
     protected void addButtonComponents(Container container, Object[] buttons,
                                  int initialIndex) {
@@ -733,17 +817,25 @@
         }
     }
 
+    /**
+     * Constructs a new instance of a {@code ButtonActionListener}.
+     *
+     * @param buttonIndex an index of the button
+     * @return a new instance of a {@code ButtonActionListener}
+     */
     protected ActionListener createButtonActionListener(int buttonIndex) {
         return new ButtonActionListener(buttonIndex);
     }
 
     /**
-     * Returns the buttons to display from the JOptionPane the receiver is
-     * providing the look and feel for. If the JOptionPane has options
+     * Returns the buttons to display from the {@code JOptionPane} the receiver is
+     * providing the look and feel for. If the {@code JOptionPane} has options
      * set, they will be provided, otherwise if the optionType is
-     * YES_NO_OPTION, yesNoOptions is returned, if the type is
-     * YES_NO_CANCEL_OPTION yesNoCancelOptions is returned, otherwise
-     * defaultButtons are returned.
+     * {@code YES_NO_OPTION}, {@code yesNoOptions} is returned, if the type is
+     * {@code YES_NO_CANCEL_OPTION} {@code yesNoCancelOptions} is returned, otherwise
+     * {@code defaultButtons} are returned.
+     *
+     * @return the buttons to display from the JOptionPane
      */
     protected Object[] getButtons() {
         if (optionPane != null) {
@@ -827,8 +919,10 @@
     }
 
     /**
-     * Returns true, basic L&amp;F wants all the buttons to have the same
+     * Returns {@code true}, basic L&amp;F wants all the buttons to have the same
      * width.
+     *
+     * @return {@code true} if all the buttons should have the same width
      */
     protected boolean getSizeButtonsToSameWidth() {
         return true;
@@ -838,6 +932,8 @@
      * Returns the initial index into the buttons to select. The index
      * is calculated from the initial value from the JOptionPane and
      * options of the JOptionPane or 0.
+     *
+     * @return the initial index into the buttons to select
      */
     protected int getInitialValueIndex() {
         if (optionPane != null) {
@@ -915,7 +1011,13 @@
      * Instantiate it only within subclasses of {@code BasicOptionPaneUI}.
      */
     public static class ButtonAreaLayout implements LayoutManager {
+        /**
+         * The value represents if the width of children should be synchronized.
+         */
         protected boolean           syncAllWidths;
+        /**
+         * The padding value.
+         */
         protected int               padding;
         /** If true, children are lumped together in parent. */
         protected boolean           centersChildren;
@@ -928,6 +1030,12 @@
          */
         private boolean useOrientation;
 
+        /**
+         * Constructs a new instance of {@code ButtonAreaLayout}.
+         *
+         * @param syncAllWidths if the width of children should be synchronized
+         * @param padding the padding value
+         */
         public ButtonAreaLayout(boolean syncAllWidths, int padding) {
             this.syncAllWidths = syncAllWidths;
             this.padding = padding;
@@ -943,27 +1051,57 @@
             this.reverseButtons = reverseButtons;
         }
 
+        /**
+         * Sets if the width of children should be synchronized.
+         *
+         * @param newValue if the width of children should be synchronized
+         */
         public void setSyncAllWidths(boolean newValue) {
             syncAllWidths = newValue;
         }
 
+        /**
+         * Returns if the width of children should be synchronized.
+         *
+         * @return if the width of children should be synchronized
+         */
         public boolean getSyncAllWidths() {
             return syncAllWidths;
         }
 
+        /**
+         * Sets the padding value.
+         *
+         * @param newPadding the new padding
+         */
         public void setPadding(int newPadding) {
             this.padding = newPadding;
         }
 
+        /**
+         * Returns the padding.
+         *
+         * @return the padding
+         */
         public int getPadding() {
             return padding;
         }
 
+        /**
+         * Sets whether or not center children should be used.
+         *
+         * @param newValue a new value
+         */
         public void setCentersChildren(boolean newValue) {
             centersChildren = newValue;
             useOrientation = false;
         }
 
+        /**
+         * Returns whether or not center children should be used.
+         *
+         * @return whether or not center children should be used
+         */
         public boolean getCentersChildren() {
             return centersChildren;
         }
@@ -1163,8 +1301,16 @@
      * Instantiate it only within subclasses of {@code BasicOptionPaneUI}.
      */
     public class ButtonActionListener implements ActionListener {
+        /**
+         * The index of the button.
+         */
         protected int buttonIndex;
 
+        /**
+         * Constructs a new instance of {@code ButtonActionListener}.
+         *
+         * @param buttonIndex an index of the button
+         */
         public ButtonActionListener(int buttonIndex) {
             this.buttonIndex = buttonIndex;
         }
--- a/src/share/classes/javax/swing/plaf/basic/BasicToolBarUI.java	Fri Jul 11 13:32:12 2014 +0400
+++ b/src/share/classes/javax/swing/plaf/basic/BasicToolBarUI.java	Fri Jul 11 16:44:11 2014 +0400
@@ -50,29 +50,65 @@
  */
 public class BasicToolBarUI extends ToolBarUI implements SwingConstants
 {
+    /**
+     * The instance of {@code JToolBar}.
+     */
     protected JToolBar toolBar;
     private boolean floating;
     private int floatingX;
     private int floatingY;
     private JFrame floatingFrame;
     private RootPaneContainer floatingToolBar;
+    /**
+     * The instance of {@code DragWindow}.
+     */
     protected DragWindow dragWindow;
     private Container dockingSource;
     private int dockingSensitivity = 0;
+    /**
+     * The index of the focused component.
+     */
     protected int focusedCompIndex = -1;
 
+    /**
+     * The background color of the docking border.
+     */
     protected Color dockingColor = null;
+    /**
+     * The background color of the not docking border.
+     */
     protected Color floatingColor = null;
+    /**
+     * The color of the docking border.
+     */
     protected Color dockingBorderColor = null;
+    /**
+     * The color of the not docking border.
+     */
     protected Color floatingBorderColor = null;
 
+    /**
+     * The instance of a {@code MouseInputListener}.
+     */
     protected MouseInputListener dockingListener;
+    /**
+     * The instance of a {@code PropertyChangeListener}.
+     */
     protected PropertyChangeListener propertyListener;
 
+    /**
+     * The instance of a {@code ContainerListener}.
+     */
     protected ContainerListener toolBarContListener;
+    /**
+     * The instance of a {@code FocusListener}.
+     */
     protected FocusListener toolBarFocusListener;
     private Handler handler;
 
+    /**
+     * The layout before floating.
+     */
     protected String constraintBeforeFloating = BorderLayout.NORTH;
 
     // Rollover button implementation.
@@ -130,6 +166,12 @@
 
     private static String FOCUSED_COMP_INDEX = "JToolBar.focusedCompIndex";
 
+    /**
+     * Constructs a new instance of {@code BasicToolBarUI}.
+     *
+     * @param c a component
+     * @return a new instance of {@code BasicToolBarUI}
+     */
     public static ComponentUI createUI( JComponent c )
     {
         return new BasicToolBarUI();
@@ -180,6 +222,9 @@
         c.putClientProperty( FOCUSED_COMP_INDEX, Integer.valueOf( focusedCompIndex ) );
     }
 
+    /**
+     * Installs default properties.
+     */
     protected void installDefaults( )
     {
         LookAndFeel.installBorder(toolBar,"ToolBar.border");
@@ -222,6 +267,9 @@
         setRolloverBorders( isRolloverBorders() );
     }
 
+    /**
+     * Uninstalls default properties.
+     */
     protected void uninstallDefaults( )
     {
         LookAndFeel.uninstallBorder(toolBar);
@@ -237,14 +285,23 @@
         nonRolloverToggleBorder = null;
     }
 
+    /**
+     * Registers components.
+     */
     protected void installComponents( )
     {
     }
 
+    /**
+     * Unregisters components.
+     */
     protected void uninstallComponents( )
     {
     }
 
+    /**
+     * Registers listeners.
+     */
     protected void installListeners( )
     {
         dockingListener = createDockingListener( );
@@ -278,6 +335,9 @@
         }
     }
 
+    /**
+     * Unregisters listeners.
+     */
     protected void uninstallListeners( )
     {
         if ( dockingListener != null )
@@ -314,6 +374,9 @@
         handler = null;
     }
 
+    /**
+     * Registers keyboard actions.
+     */
     protected void installKeyboardActions( )
     {
         InputMap km = getInputMap(JComponent.
@@ -342,6 +405,9 @@
         map.put(new Actions(Actions.NAVIGATE_DOWN));
     }
 
+    /**
+     * Unregisters keyboard actions.
+     */
     protected void uninstallKeyboardActions( )
     {
         SwingUtilities.replaceUIActionMap(toolBar, null);
@@ -350,7 +416,12 @@
                                          null);
     }
 
-    protected void navigateFocusedComp( int direction )
+    /**
+     * Navigates the focused component.
+     *
+     * @param direction a direction
+     */
+    protected void navigateFocusedComp(int direction)
     {
         int nComp = toolBar.getComponentCount();
         int j;
@@ -411,6 +482,7 @@
      * <p>
      * Override this method to provide an alternate rollover border.
      *
+     * @return a rollover border for toolbar components
      * @since 1.4
      */
     protected Border createRolloverBorder() {
@@ -434,6 +506,7 @@
      * <p>
      * Override this method to provide an alternate rollover border.
      *
+     * @return the non rollover border for toolbar components
      * @since 1.4
      */
     protected Border createNonRolloverBorder() {
@@ -465,6 +538,9 @@
 
     /**
      * No longer used, use BasicToolBarUI.createFloatingWindow(JToolBar)
+     *
+     * @param toolbar an instance of {@code JToolBar}
+     * @return an instance of {@code JFrame}
      * @see #createFloatingWindow
      */
     protected JFrame createFloatingFrame(JToolBar toolbar) {
@@ -502,7 +578,9 @@
     /**
      * Creates a window which contains the toolbar after it has been
      * dragged out from its container
-     * @return a <code>RootPaneContainer</code> object, containing the toolbar.
+     *
+     * @param toolbar an instance of {@code JToolBar}
+     * @return a {@code RootPaneContainer} object, containing the toolbar
      * @since 1.4
      */
     protected RootPaneContainer createFloatingWindow(JToolBar toolbar) {
@@ -555,6 +633,12 @@
         return dialog;
     }
 
+    /**
+     * Returns an instance of {@code DragWindow}.
+     *
+     * @param toolbar an instance of {@code JToolBar}
+     * @return an instance of {@code DragWindow}
+     */
     protected DragWindow createDragWindow(JToolBar toolbar) {
         Window frame = null;
         if(toolBar != null) {
@@ -776,15 +860,32 @@
         }
     }
 
+    /**
+     * Sets the floating location.
+     *
+     * @param x an X coordinate
+     * @param y an Y coordinate
+     */
     public void setFloatingLocation(int x, int y) {
         floatingX = x;
         floatingY = y;
     }
 
+    /**
+     * Returns {@code true} if the {@code JToolBar} is floating
+     *
+     * @return {@code true} if the {@code JToolBar} is floating
+     */
     public boolean isFloating() {
         return floating;
     }
 
+    /**
+     * Sets the floating property.
+     *
+     * @param b {@code true} if the {@code JToolBar} is floating
+     * @param p the position
+     */
     public void setFloating(boolean b, Point p) {
         if (toolBar.isFloatable()) {
             boolean visible = false;
@@ -863,6 +964,11 @@
         return orientation;
     }
 
+    /**
+     * Sets the tool bar's orientation.
+     *
+     * @param orientation the new orientation
+     */
     public void setOrientation(int orientation)
     {
         toolBar.setOrientation( orientation );
@@ -873,6 +979,8 @@
 
     /**
      * Gets the color displayed when over a docking area
+     *
+     * @return the color displayed when over a docking area
      */
     public Color getDockingColor() {
         return dockingColor;
@@ -880,6 +988,8 @@
 
     /**
      * Sets the color displayed when over a docking area
+     *
+     * @param c the new color
      */
    public void setDockingColor(Color c) {
         this.dockingColor = c;
@@ -887,6 +997,8 @@
 
     /**
      * Gets the color displayed when over a floating area
+     *
+     * @return the color displayed when over a floating area
      */
     public Color getFloatingColor() {
         return floatingColor;
@@ -894,6 +1006,8 @@
 
     /**
      * Sets the color displayed when over a floating area
+     *
+     * @param c the new color
      */
     public void setFloatingColor(Color c) {
         this.floatingColor = c;
@@ -912,6 +1026,13 @@
         return false;
     }
 
+    /**
+     * Returns {@code true} if the {@code JToolBar} can dock at the given position.
+     *
+     * @param c a component
+     * @param p a position
+     * @return {@code true} if the {@code JToolBar} can dock at the given position
+     */
     public boolean canDock(Component c, Point p) {
         return (p != null && getDockingConstraint(c, p) != null);
     }
@@ -952,6 +1073,13 @@
         return null;
     }
 
+    /**
+     * The method is used to drag {@code DragWindow} during the {@code JToolBar}
+     * is being dragged.
+     *
+     * @param position the relative to the {@code JTollBar} position
+     * @param origin the screen position of {@code JToolBar} before dragging
+     */
     protected void dragTo(Point position, Point origin)
     {
         if (toolBar.isFloatable())
@@ -1002,6 +1130,13 @@
         }
     }
 
+    /**
+     * The method is called at end of dragging to place the frame in either
+     * its original place or in its floating frame.
+     *
+     * @param position the relative to the {@code JTollBar} position
+     * @param origin the screen position of {@code JToolBar} before dragging
+     */
     protected void floatAt(Point position, Point origin)
     {
         if(toolBar.isFloatable())
@@ -1044,26 +1179,51 @@
         return handler;
     }
 
+    /**
+     * Returns an instance of {@code ContainerListener}.
+     *
+     * @return an instance of {@code ContainerListener}
+     */
     protected ContainerListener createToolBarContListener( )
     {
         return getHandler();
     }
 
+    /**
+     * Returns an instance of {@code FocusListener}.
+     *
+     * @return an instance of {@code FocusListener}
+     */
     protected FocusListener createToolBarFocusListener( )
     {
         return getHandler();
     }
 
+    /**
+     * Returns an instance of {@code PropertyChangeListener}.
+     *
+     * @return an instance of {@code PropertyChangeListener}
+     */
     protected PropertyChangeListener createPropertyListener()
     {
         return getHandler();
     }
 
+    /**
+     * Returns an instance of {@code MouseInputListener}.
+     *
+     * @return an instance of {@code MouseInputListener}
+     */
     protected MouseInputListener createDockingListener( ) {
         getHandler().tb = toolBar;
         return getHandler();
     }
 
+    /**
+     * Constructs a new instance of {@code WindowListener}.
+     *
+     * @return a new instance of {@code WindowListener}
+     */
     protected WindowListener createFrameListener() {
         return new FrameListener();
     }
@@ -1241,6 +1401,9 @@
         }
     }
 
+    /**
+     * The class listens for window events.
+     */
     protected class FrameListener extends WindowAdapter {
         public void windowClosing(WindowEvent w) {
             if (toolBar.isFloatable()) {
@@ -1276,6 +1439,9 @@
 
     }
 
+    /**
+     * The class listens for component events.
+     */
     protected class ToolBarContListener implements ContainerListener {
         // NOTE: This class exists only for backward compatibility. All
         // its functionality has been moved into Handler. If you need to add
@@ -1291,6 +1457,9 @@
 
     }
 
+    /**
+     * The class listens for focus events.
+     */
     protected class ToolBarFocusListener implements FocusListener {
         // NOTE: This class exists only for backward compatibility. All
         // its functionality has been moved into Handler. If you need to add
@@ -1305,6 +1474,9 @@
             }
     }
 
+    /**
+     * The class listens for property changed events.
+     */
     protected class PropertyListener implements PropertyChangeListener {
         // NOTE: This class exists only for backward compatibility. All
         // its functionality has been moved into Handler. If you need to add
@@ -1324,10 +1496,24 @@
         // its functionality has been moved into Handler. If you need to add
         // new functionality add it to the Handler, but make sure this
         // class calls into the Handler.
+        /**
+         * The instance of {@code JToolBar}.
+         */
         protected JToolBar toolBar;
+        /**
+         * {@code true} if the {@code JToolBar} is being dragged.
+         */
         protected boolean isDragging = false;
+        /**
+         * The origin point.
+         */
         protected Point origin = null;
 
+        /**
+         * Constructs a new instance of {@code DockingListener}.
+         *
+         * @param t an instance of {@code JToolBar}
+         */
         public DockingListener(JToolBar t) {
             this.toolBar = t;
             getHandler().tb = t;
@@ -1373,6 +1559,9 @@
         }
     }
 
+    /**
+     * The window which appears during dragging the {@code JToolBar}.
+     */
     @SuppressWarnings("serial") // Same-version serialization only
     protected class DragWindow extends Window
     {
@@ -1396,6 +1585,11 @@
         return orientation;
     }
 
+        /**
+         * Sets the orientation.
+         *
+         * @param o the new orientation
+         */
         public void setOrientation(int o) {
             if(isShowing()) {
                 if (o == this.orientation)
@@ -1416,14 +1610,29 @@
             }
         }
 
+        /**
+         * Returns the offset.
+         *
+         * @return the offset
+         */
         public Point getOffset() {
             return offset;
         }
 
+        /**
+         * Sets the offset.
+         *
+         * @param p the new offset
+         */
         public void setOffset(Point p) {
             this.offset = p;
         }
 
+        /**
+         * Sets the border color.
+         *
+         * @param c the new border color
+         */
         public void setBorderColor(Color c) {
             if (this.borderColor == c)
                 return;
@@ -1431,6 +1640,11 @@
             repaint();
         }
 
+        /**
+         * Returns the border color.
+         *
+         * @return the border color
+         */
         public Color getBorderColor() {
             return this.borderColor;
         }