changeset 10251:a8aa05835ab2

8046590: fix doclint issues in swing classes, part 1 of 4 Reviewed-by: alexsch Contributed-by: Steven Sides <steve.sides@oracle.com>
author yan
date Fri, 04 Jul 2014 12:56:58 +0400
parents 7044e9901b8f
children f44b1b98c288
files src/share/classes/javax/swing/AbstractListModel.java src/share/classes/javax/swing/CellRendererPane.java src/share/classes/javax/swing/DefaultCellEditor.java src/share/classes/javax/swing/DefaultDesktopManager.java src/share/classes/javax/swing/DefaultListModel.java src/share/classes/javax/swing/DefaultListSelectionModel.java src/share/classes/javax/swing/DefaultRowSorter.java src/share/classes/javax/swing/InputMap.java src/share/classes/javax/swing/JCheckBox.java src/share/classes/javax/swing/JCheckBoxMenuItem.java src/share/classes/javax/swing/JEditorPane.java src/share/classes/javax/swing/JFileChooser.java src/share/classes/javax/swing/JFrame.java src/share/classes/javax/swing/JMenu.java src/share/classes/javax/swing/JMenuBar.java src/share/classes/javax/swing/JSlider.java src/share/classes/javax/swing/JTabbedPane.java src/share/classes/javax/swing/JTable.java src/share/classes/javax/swing/MenuElement.java src/share/classes/javax/swing/MenuSelectionManager.java src/share/classes/javax/swing/RowFilter.java src/share/classes/javax/swing/SortingFocusTraversalPolicy.java src/share/classes/javax/swing/Spring.java src/share/classes/javax/swing/UIManager.java
diffstat 24 files changed, 247 insertions(+), 93 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/javax/swing/AbstractListModel.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/AbstractListModel.java	Fri Jul 04 12:56:58 2014 +0400
@@ -202,6 +202,7 @@
      * If no such listeners exist,
      * this method returns an empty array.
      *
+     * @param <T> the type of {@code EventListener} class being requested
      * @param listenerType  the type of listeners requested;
      *          this parameter should specify an interface
      *          that descends from <code>java.util.EventListener</code>
--- a/src/share/classes/javax/swing/CellRendererPane.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/CellRendererPane.java	Fri Jul 04 12:56:58 2014 +0400
@@ -190,8 +190,12 @@
 // Accessibility support
 ////////////////
 
+    /**
+     * {@code AccessibleContext} associated with this {@code CellRendererPan}
+     */
     protected AccessibleContext accessibleContext = null;
 
+
     /**
      * Gets the AccessibleContext associated with this CellRendererPane.
      * For CellRendererPanes, the AccessibleContext takes the form of an
--- a/src/share/classes/javax/swing/DefaultCellEditor.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/DefaultCellEditor.java	Fri Jul 04 12:56:58 2014 +0400
@@ -353,6 +353,7 @@
         * Returns true to indicate that editing has begun.
         *
         * @param anEvent          the event
+        * @return true to indicate editing has begun
         */
         public boolean startCellEditing(EventObject anEvent) {
             return true;
--- a/src/share/classes/javax/swing/DefaultDesktopManager.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/DefaultDesktopManager.java	Fri Jul 04 12:56:58 2014 +0400
@@ -462,7 +462,12 @@
         f.revalidate();
     }
 
-    /** Convenience method to remove the desktopIcon of <b>f</b> is necessary. */
+    /**
+     * Convenience method to remove the desktopIcon of <b>f</b> is necessary.
+     *
+     * @param f the {@code JInternalFrame} for which to remove the
+     *          {@code desktopIcon}
+     */
     protected void removeIconFor(JInternalFrame f) {
         JInternalFrame.JDesktopIcon di = f.getDesktopIcon();
         Container c = di.getParent();
@@ -472,10 +477,13 @@
         }
     }
 
-    /** The iconifyFrame() code calls this to determine the proper bounds
-      * for the desktopIcon.
-      */
-
+    /**
+     * The {@code iconifyFrame()} code calls this to determine the proper bounds
+     * for the desktopIcon.
+     *
+     * @param f the {@code JInternalFrame} of interest
+     * @return a {@code Rectangle} containing bounds for the {@code desktopIcon}
+     */
     protected Rectangle getBoundsForIconOf(JInternalFrame f) {
       //
       // Get the icon for this internal frame and its preferred size
@@ -592,6 +600,9 @@
     /**
      * Sets that the component has been iconized and the bounds of the
      * <code>desktopIcon</code> are valid.
+     *
+     * @param f     the {@code JInternalFrame} of interest
+     * @param value a {@code Boolean} signifying if component has been iconized
      */
     protected void setWasIcon(JInternalFrame f, Boolean value)  {
         if (value != null) {
--- a/src/share/classes/javax/swing/DefaultListModel.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/DefaultListModel.java	Fri Jul 04 12:56:58 2014 +0400
@@ -444,6 +444,7 @@
      * (<code>index &lt; 0 || index &gt;= size()</code>).
      *
      * @param index index of element to return
+     * @return the element at the specified position in this list
      */
     public E get(int index) {
         return delegate.elementAt(index);
--- a/src/share/classes/javax/swing/DefaultListSelectionModel.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/DefaultListSelectionModel.java	Fri Jul 04 12:56:58 2014 +0400
@@ -160,6 +160,9 @@
      * Notifies <code>ListSelectionListeners</code> that the value
      * of the selection, in the closed interval <code>firstIndex</code>,
      * <code>lastIndex</code>, has changed.
+     *
+     * @param firstIndex the first index in the interval
+     * @param lastIndex the last index in the interval
      */
     protected void fireValueChanged(int firstIndex, int lastIndex) {
         fireValueChanged(firstIndex, lastIndex, getValueIsAdjusting());
@@ -231,6 +234,7 @@
      * If no such listeners exist,
      * this method returns an empty array.
      *
+     * @param <T> the type of {@code EventListener} class being requested
      * @param listenerType  the type of listeners requested;
      *          this parameter should specify an interface
      *          that descends from <code>java.util.EventListener</code>
@@ -332,6 +336,8 @@
 
     /**
      * Sets the value of the leadAnchorNotificationEnabled flag.
+     *
+     * @param flag boolean value for {@code leadAnchorNotificationEnabled}
      * @see             #isLeadAnchorNotificationEnabled()
      */
     public void setLeadAnchorNotificationEnabled(boolean flag) {
--- a/src/share/classes/javax/swing/DefaultRowSorter.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/DefaultRowSorter.java	Fri Jul 04 12:56:58 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 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
@@ -712,6 +712,8 @@
      *
      * @param column the index of the column to test, in terms of the
      *        underlying model
+     * @return true if values are to be converted to strings before doing
+     *              comparisons when sorting
      * @throws IndexOutOfBoundsException if <code>column</code> is not valid
      */
     protected boolean useToString(int column) {
--- a/src/share/classes/javax/swing/InputMap.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/InputMap.java	Fri Jul 04 12:56:58 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 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
@@ -32,15 +32,12 @@
 import java.util.Set;
 
 /**
- * <code>InputMap</code> provides a binding between an input event
- * (currently only <code>KeyStroke</code>s are used)
- * and an <code>Object</code>. <code>InputMap</code>s
- * are usually used with an <code>ActionMap</code>,
- * to determine an <code>Action</code> to perform
- * when a key is pressed.
- * An <code>InputMap</code> can have a parent
- * that is searched for bindings not defined in the <code>InputMap</code>.
- * <p>As with <code>ActionMap</code> if you create a cycle, eg:
+ * {@code InputMap} provides a binding between an input event (currently only
+ * {@code KeyStroke}s are used) and an {@code Object}. {@code InputMap}s are
+ * usually used with an {@code ActionMap}, to determine an {@code Action} to
+ * perform when a key is pressed. An {@code InputMap} can have a parent that
+ * is searched for bindings not defined in the {@code InputMap}.
+ * <p>As with {@code ActionMap} if you create a cycle, eg:
  * <pre>
  *   InputMap am = new InputMap();
  *   InputMap bm = new InputMap():
@@ -61,34 +58,37 @@
 
 
     /**
-     * Creates an <code>InputMap</code> with no parent and no mappings.
+     * Creates an {@code InputMap} with no parent and no mappings.
      */
     public InputMap() {
     }
 
     /**
-     * Sets this <code>InputMap</code>'s parent.
+     * Sets this {@code InputMap}'s parent.
      *
-     * @param map  the <code>InputMap</code> that is the parent of this one
+     * @param map the {@code InputMap} that is the parent of this one
      */
     public void setParent(InputMap map) {
         this.parent = map;
     }
 
     /**
-     * Gets this <code>InputMap</code>'s parent.
+     * Gets this {@code InputMap}'s parent.
      *
-     * @return map  the <code>InputMap</code> that is the parent of this one,
-     *              or null if this <code>InputMap</code> has no parent
+     * @return map the {@code InputMap} that is the parent of this one,
+     *             or null if this {@code InputMap} has no parent
      */
     public InputMap getParent() {
         return parent;
     }
 
     /**
-     * Adds a binding for <code>keyStroke</code> to <code>actionMapKey</code>.
-     * If <code>actionMapKey</code> is null, this removes the current binding
-     * for <code>keyStroke</code>.
+     * Adds a binding for {@code keyStroke} to {@code actionMapKey}.
+     * If {@code actionMapKey} is null, this removes the current binding
+     * for {@code keyStroke}.
+     *
+     * @param keyStroke a {@code KeyStroke}
+     * @param actionMapKey an action map key
      */
     public void put(KeyStroke keyStroke, Object actionMapKey) {
         if (keyStroke == null) {
@@ -106,8 +106,11 @@
     }
 
     /**
-     * Returns the binding for <code>keyStroke</code>, messaging the
-     * parent <code>InputMap</code> if the binding is not locally defined.
+     * Returns the binding for {@code keyStroke}, messaging the
+     * parent {@code InputMap} if the binding is not locally defined.
+     *
+     * @param keyStroke the {@code KeyStroke} for which to get the binding
+     * @return the binding for {@code keyStroke}
      */
     public Object get(KeyStroke keyStroke) {
         if (arrayTable == null) {
@@ -131,8 +134,9 @@
     }
 
     /**
-     * Removes the binding for <code>key</code> from this
-     * <code>InputMap</code>.
+     * Removes the binding for {@code key} from this {@code InputMap}.
+     *
+     * @param key the {@code KeyStroke} for which to remove the binding
      */
     public void remove(KeyStroke key) {
         if (arrayTable != null) {
@@ -141,7 +145,7 @@
     }
 
     /**
-     * Removes all the mappings from this <code>InputMap</code>.
+     * Removes all the mappings from this {@code InputMap}.
      */
     public void clear() {
         if (arrayTable != null) {
@@ -150,7 +154,10 @@
     }
 
     /**
-     * Returns the <code>KeyStroke</code>s that are bound in this <code>InputMap</code>.
+     * Returns the {@code KeyStroke}s that are bound in this {@code InputMap}.
+     *
+     * @return an array of the {@code KeyStroke}s that are bound in this
+     *         {@code InputMap}
      */
     public KeyStroke[] keys() {
         if (arrayTable == null) {
@@ -162,7 +169,9 @@
     }
 
     /**
-     * Returns the number of <code>KeyStroke</code> bindings.
+     * Returns the number of {@code KeyStroke} bindings.
+     *
+     * @return the number of {@code KeyStroke} bindings
      */
     public int size() {
         if (arrayTable == null) {
@@ -172,9 +181,12 @@
     }
 
     /**
-     * Returns an array of the <code>KeyStroke</code>s defined in this
-     * <code>InputMap</code> and its parent. This differs from <code>keys()</code> in that
-     * this method includes the keys defined in the parent.
+     * Returns an array of the {@code KeyStroke}s defined in this
+     * {@code InputMap} and its parent. This differs from {@code keys()}
+     * in that this method includes the keys defined in the parent.
+     *
+     * @return an array of the {@code KeyStroke}s defined in this
+     *         {@code InputMap} and its parent
      */
     public KeyStroke[] allKeys() {
         int             count = size();
--- a/src/share/classes/javax/swing/JCheckBox.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JCheckBox.java	Fri Jul 04 12:56:58 2014 +0400
@@ -132,6 +132,7 @@
      * Creates a check box where properties are taken from the
      * Action supplied.
      *
+     * @param a the {@code Action} used to specify the new check box
      * @since 1.3
      */
     public JCheckBox(Action a) {
--- a/src/share/classes/javax/swing/JCheckBoxMenuItem.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JCheckBoxMenuItem.java	Fri Jul 04 12:56:58 2014 +0400
@@ -109,7 +109,7 @@
     /**
      * Creates an initially unselected check box menu item with an icon.
      *
-     * @param icon the icon of the CheckBoxMenuItem.
+     * @param icon the icon of the {@code JCheckBoxMenuItem}.
      */
     public JCheckBoxMenuItem(Icon icon) {
         this(null, icon, false);
@@ -118,7 +118,7 @@
     /**
      * Creates an initially unselected check box menu item with text.
      *
-     * @param text the text of the CheckBoxMenuItem
+     * @param text the text of the {@code JCheckBoxMenuItem}
      */
     public JCheckBoxMenuItem(String text) {
         this(text, null, false);
@@ -128,6 +128,7 @@
      * Creates a menu item whose properties are taken from the
      * Action supplied.
      *
+     * @param a the action of the {@code JCheckBoxMenuItem}
      * @since 1.3
      */
     public JCheckBoxMenuItem(Action a) {
@@ -138,8 +139,8 @@
     /**
      * Creates an initially unselected check box menu item with the specified text and icon.
      *
-     * @param text the text of the CheckBoxMenuItem
-     * @param icon the icon of the CheckBoxMenuItem
+     * @param text the text of the {@code JCheckBoxMenuItem}
+     * @param icon the icon of the {@code JCheckBoxMenuItem}
      */
     public JCheckBoxMenuItem(String text, Icon icon) {
         this(text, icon, false);
--- a/src/share/classes/javax/swing/JEditorPane.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JEditorPane.java	Fri Jul 04 12:56:58 2014 +0400
@@ -1251,11 +1251,12 @@
     }
 
     /**
-     * Returns the currently registered <code>EditorKit</code>
-     * class name for the type <code>type</code>.
+     * Returns the currently registered {@code EditorKit} class name for the
+     * type {@code type}.
      *
-     * @param type  the non-<code>null</code> content type
-     *
+     * @param type  the non-{@code null} content type
+     * @return a {@code String} containing the {@code EditorKit} class name
+     *         for {@code type}
      * @since 1.3
      */
     public static String getEditorKitClassNameForContentType(String type) {
--- a/src/share/classes/javax/swing/JFileChooser.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JFileChooser.java	Fri Jul 04 12:56:58 2014 +0400
@@ -330,6 +330,8 @@
     /**
      * Constructs a <code>JFileChooser</code> using the given
      * <code>FileSystemView</code>.
+     *
+     * @param fsv a {@code FileSystemView}
      */
     public JFileChooser(FileSystemView fsv) {
         this((File) null, fsv);
@@ -339,6 +341,10 @@
     /**
      * Constructs a <code>JFileChooser</code> using the given current directory
      * and <code>FileSystemView</code>.
+     *
+     * @param currentDirectory a {@code File} object specifying the path to a
+     *                         file or directory
+     * @param fsv a {@code FileSystemView}
      */
     public JFileChooser(File currentDirectory, FileSystemView fsv) {
         setup(fsv);
@@ -348,6 +354,10 @@
     /**
      * Constructs a <code>JFileChooser</code> using the given current directory
      * path and <code>FileSystemView</code>.
+     *
+     * @param currentDirectoryPath a {@code String} specifying the path to a file
+     *                             or directory
+     * @param fsv a {@code FileSystemView}
      */
     public JFileChooser(String currentDirectoryPath, FileSystemView fsv) {
         setup(fsv);
@@ -360,6 +370,8 @@
 
     /**
      * Performs common constructor initialization and setup.
+     *
+     * @param view the {@code FileSystemView} used for setup
      */
     protected void setup(FileSystemView view) {
         installShowFilesListener();
@@ -512,6 +524,8 @@
     /**
      * Returns a list of selected files if the file chooser is
      * set to allow multiple selection.
+     *
+     * @return an array of selected {@code File}s
      */
     public File[] getSelectedFiles() {
         if(selectedFiles == null) {
@@ -525,6 +539,7 @@
      * Sets the list of selected files if the file chooser is
      * set to allow multiple selection.
      *
+     * @param selectedFiles an array {@code File}s to be selected
      * @beaninfo
      *       bound: true
      * description: The list of selected files if the chooser is in multiple selection mode.
@@ -971,6 +986,7 @@
     /**
      * Gets the string that goes in the <code>JFileChooser</code>'s titlebar.
      *
+     * @return the string from the {@code JFileChooser} window's title bar
      * @see #setDialogTitle
      */
     public String getDialogTitle() {
@@ -1158,6 +1174,8 @@
      * Removes a filter from the list of user choosable file filters. Returns
      * true if the file filter was removed.
      *
+     * @param f the file filter to be removed
+     * @return true if the file filter was removed, false otherwise
      * @see #addChoosableFileFilter
      * @see #getChoosableFileFilters
      * @see #resetChoosableFileFilters
@@ -1215,6 +1233,8 @@
     /**
      * Returns the <code>AcceptAll</code> file filter.
      * For example, on Microsoft Windows this would be All Files (*.*).
+     *
+     * @return the {@code AcceptAll} file filter
      */
     public FileFilter getAcceptAllFileFilter() {
         FileFilter filter = null;
@@ -1240,8 +1260,10 @@
     * If false, the <code>AcceptAll</code> file filter is removed from
     * the list of available file filters.
     * If true, the <code>AcceptAll</code> file filter will become the
-    * the actively used file filter.
+    * actively used file filter.
     *
+    * @param b a {@code boolean} which determines whether the {@code AcceptAll}
+    *          file filter is an available choice in the choosable filter list
     * @beaninfo
     *   preferred: true
     *       bound: true
@@ -1284,6 +1306,7 @@
      * any listeners that the accessory might have registered with the
      * file chooser.
      *
+     * @param newAccessory the accessory component to be set
      * @beaninfo
      *   preferred: true
      *       bound: true
@@ -1355,6 +1378,7 @@
      * Convenience call that determines if files are selectable based on the
      * current file selection mode.
      *
+     * @return true if files are selectable, false otherwise
      * @see #setFileSelectionMode
      * @see #getFileSelectionMode
      */
@@ -1366,6 +1390,7 @@
      * Convenience call that determines if directories are selectable based
      * on the current file selection mode.
      *
+     * @return true if directories are selectable, false otherwise
      * @see #setFileSelectionMode
      * @see #getFileSelectionMode
      */
@@ -1487,9 +1512,10 @@
     }
 
     /**
-     * Sets the file view to used to retrieve UI information, such as
+     * Sets the file view to be used to retrieve UI information, such as
      * the icon that represents a file or the type description of a file.
      *
+     * @param fileView a {@code FileView} to be used to retrieve UI information
      * @beaninfo
      *   preferred: true
      *       bound: true
@@ -1506,6 +1532,7 @@
     /**
      * Returns the current file view.
      *
+     * @return the current file view
      * @see #setFileView
      */
     public FileView getFileView() {
@@ -1765,6 +1792,8 @@
      * notification on this event type. The event instance
      * is lazily created using the <code>command</code> parameter.
      *
+     * @param command a string that may specify a command associated with
+     *                the event
      * @see EventListenerList
      */
     protected void fireActionPerformed(String command) {
@@ -1973,6 +2002,9 @@
 // Accessibility support
 ////////////////
 
+    /**
+     * {@code AccessibleContext} associated with this {@code JFileChooser}
+     */
     protected AccessibleContext accessibleContext = null;
 
     /**
--- a/src/share/classes/javax/swing/JFrame.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JFrame.java	Fri Jul 04 12:56:58 2014 +0400
@@ -275,6 +275,8 @@
     /**
      * Called by the constructor methods to create the default
      * <code>rootPane</code>.
+     *
+     * @return a new {@code JRootPane}
      */
     protected JRootPane createRootPane() {
         JRootPane rp = new JRootPane();
@@ -874,7 +876,9 @@
 // Accessibility support
 ////////////////
 
-    /** The accessible context property. */
+    /**
+     * The accessible context property.
+     */
     protected AccessibleContext accessibleContext = null;
 
     /**
--- a/src/share/classes/javax/swing/JMenu.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JMenu.java	Fri Jul 04 12:56:58 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
@@ -608,16 +608,18 @@
      * it to the end of this menu.
      *
      * @param s the string for the menu item to be added
+     * @return the new {@code JMenuItem}
      */
     public JMenuItem add(String s) {
         return add(new JMenuItem(s));
     }
 
     /**
-     * Creates a new menu item attached to the specified
-     * <code>Action</code> object and appends it to the end of this menu.
+     * Creates a new menu item attached to the specified {@code Action} object
+     * and appends it to the end of this menu.
      *
-     * @param a the <code>Action</code> for the menu item to be added
+     * @param a the {@code Action} for the menu item to be added
+     * @return the new {@code JMenuItem}
      * @see Action
      */
     public JMenuItem add(Action a) {
@@ -653,8 +655,11 @@
     }
 
     /**
-     * Returns a properly configured <code>PropertyChangeListener</code>
-     * which updates the control as changes to the <code>Action</code> occur.
+     * Returns a properly configured {@code PropertyChangeListener}
+     * which updates the control as changes to the {@code Action} occur.
+     *
+     * @param b a menu item for which to create a {@code PropertyChangeListener}
+     * @return a {@code PropertyChangeListener} for {@code b}
      */
     protected PropertyChangeListener createActionChangeListener(JMenuItem b) {
         return b.createActionPropertyChangeListener0(b.getAction());
@@ -714,6 +719,7 @@
      * @param a the <code>Action</code> object for the menu item to add
      * @param pos an integer specifying the position at which to add the
      *               new menu item
+     * @return the new menu item
      * @exception IllegalArgumentException if the value of
      *                  <code>pos</code> &lt; 0
      */
@@ -748,16 +754,16 @@
     }
 
     /**
-     * Returns the <code>JMenuItem</code> at the specified position.
-     * If the component at <code>pos</code> is not a menu item,
-     * <code>null</code> is returned.
+     * Returns the {@code JMenuItem} at the specified position.
+     * If the component at {@code pos} is not a menu item,
+     * {@code null} is returned.
      * This method is included for AWT compatibility.
      *
-     * @param pos    an integer specifying the position
-     * @exception   IllegalArgumentException if the value of
-     *                       <code>pos</code> &lt; 0
+     * @param pos  an integer specifying the position
      * @return  the menu item at the specified position; or <code>null</code>
      *          if the item as the specified position is not a menu item
+     * @exception  IllegalArgumentException if the value of
+     *             {@code pos} &lt; 0
      */
     public JMenuItem getItem(int pos) {
         if (pos < 0) {
@@ -975,6 +981,8 @@
     /**
      * Returns the popupmenu associated with this menu.  If there is
      * no popupmenu, it will create one.
+     *
+     * @return the {@code JPopupMenu} associated with this menu
      */
     public JPopupMenu getPopupMenu() {
         ensurePopupMenuCreated();
@@ -1159,6 +1167,8 @@
         JPopupMenu popupMenu;
         /**
          *  Create the window listener for the specified popup.
+         *
+         * @param p the popup menu for which to create a listener
          * @since 1.4
          */
         public WinListener(JPopupMenu p) {
--- a/src/share/classes/javax/swing/JMenuBar.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JMenuBar.java	Fri Jul 04 12:56:58 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
@@ -124,6 +124,8 @@
 
     /**
      * Returns the menubar's current UI.
+     *
+     * @return a {@code MenuBarUI} which is the menubar's current L&amp;F object
      * @see #setUI
      */
     public MenuBarUI getUI() {
--- a/src/share/classes/javax/swing/JSlider.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JSlider.java	Fri Jul 04 12:56:58 2014 +0400
@@ -281,6 +281,8 @@
     /**
      * Creates a horizontal slider using the specified
      * BoundedRangeModel.
+     *
+     * @param brm a {@code BoundedRangeModel} for the slider
      */
     public JSlider(BoundedRangeModel brm)
     {
@@ -363,6 +365,8 @@
      * {@code fireStateChanged} method to forward {@code ChangeEvent}s
      * to the {@code ChangeListener}s that have been added directly to the
      * slider.
+     *
+     * @return a instance of new {@code ChangeListener}
      * @see #changeListener
      * @see #fireStateChanged
      * @see javax.swing.event.ChangeListener
--- a/src/share/classes/javax/swing/JTabbedPane.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JTabbedPane.java	Fri Jul 04 12:56:58 2014 +0400
@@ -278,6 +278,7 @@
      * can override this to return a subclass of <code>ModelListener</code> or
      * another <code>ChangeListener</code> implementation.
      *
+     * @return a {@code ChangeListener}
      * @see #fireStateChanged
      */
     protected ChangeListener createChangeListener() {
@@ -423,6 +424,7 @@
     /**
      * Returns the model associated with this tabbedpane.
      *
+     * @return the {@code SingleSelectionModel} associated with this tabbedpane
      * @see #setModel
      */
     public SingleSelectionModel getModel() {
@@ -459,6 +461,8 @@
 
     /**
      * Returns the placement of the tabs for this tabbedpane.
+     *
+     * @return an {@code int} specifying the placement for the tabs
      * @see #setTabPlacement
      */
     public int getTabPlacement() {
@@ -507,6 +511,8 @@
     /**
      * Returns the policy used by the tabbedpane to layout the tabs when all the
      * tabs will not fit within a single run.
+     *
+     * @return an {@code int} specifying the policy used to layout the tabs
      * @see #setTabLayoutPolicy
      * @since 1.4
      */
@@ -664,6 +670,7 @@
      * will automatically set the <code>selectedIndex</code> to the index
      * corresponding to the specified component.
      *
+     * @param c the selected {@code Component} for this {@code TabbedPane}
      * @exception IllegalArgumentException if component not found in tabbed
      *          pane
      * @see #getSelectedComponent
--- a/src/share/classes/javax/swing/JTable.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/JTable.java	Fri Jul 04 12:56:58 2014 +0400
@@ -865,6 +865,8 @@
     /**
      * Equivalent to <code>new JScrollPane(aTable)</code>.
      *
+     * @param aTable a {@code JTable} to be used for the scroll pane
+     * @return a {@code JScrollPane} created using {@code aTable}
      * @deprecated As of Swing version 1.0.2,
      * replaced by <code>new JScrollPane(aTable)</code>.
      */
@@ -1961,6 +1963,7 @@
      * <code>JList</code>. See the <code>setSelectionMode</code> method
      * in <code>JList</code> for details about the modes.
      *
+     * @param selectionMode the mode used by the row and column selection models
      * @see JList#setSelectionMode
      * @beaninfo
      * description: The selection mode used by the row and column selection models.
@@ -2321,6 +2324,7 @@
      * Returns true if the specified index is in the valid range of rows,
      * and the row at that index is selected.
      *
+     * @param row a row in the row model
      * @return true if <code>row</code> is a valid index and the row at
      *              that index is selected (where 0 is the first row)
      */
@@ -3174,6 +3178,8 @@
 
     /**
      * Sizes the table columns to fit the available space.
+     *
+     * @param lastColumnOnly determines whether to resize last column only
      * @deprecated As of Swing version 1.0.3,
      * replaced by <code>doLayout()</code>.
      * @see #doLayout
@@ -6692,7 +6698,7 @@
 
     // Listeners to echo changes to the AccessiblePropertyChange mechanism
 
-        /*
+        /**
          * Describes a change in the accessible table model.
          */
         protected class AccessibleJTableModelChange
@@ -6737,6 +6743,8 @@
 
         /**
          * Track changes to the table contents
+         *
+         * @param e a {@code TableModelEvent} describing the event
          */
         public void tableChanged(TableModelEvent e) {
            firePropertyChange(AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,
@@ -6764,6 +6772,8 @@
 
         /**
          * Track changes to the table contents (row insertions)
+         *
+         * @param e a {@code TableModelEvent} describing the event
          */
         public void tableRowsInserted(TableModelEvent e) {
            firePropertyChange(AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,
@@ -6789,6 +6799,8 @@
 
         /**
          * Track changes to the table contents (row deletions)
+         *
+         * @param e a {@code TableModelEvent} describing the event
          */
         public void tableRowsDeleted(TableModelEvent e) {
            firePropertyChange(AccessibleContext.ACCESSIBLE_VISIBLE_DATA_PROPERTY,
@@ -7922,6 +7934,11 @@
 
             /**
              *  Constructs an <code>AccessibleJTableHeaderEntry</code>.
+             *
+             * @param t a {@code JTable}
+             * @param r an {@code int} specifying a row
+             * @param c an {@code int} specifying a column
+             * @param i an {@code int} specifying the index to this cell
              * @since 1.4
              */
             public AccessibleJTableCell(JTable t, int r, int c, int i) {
--- a/src/share/classes/javax/swing/MenuElement.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/MenuElement.java	Fri Jul 04 12:56:58 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2003, 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
@@ -29,7 +29,7 @@
 
 /**
  * Any component that can be placed into a menu should implement this interface.
- * This interface is used by <code>MenuSelectionManager</code>
+ * This interface is used by {@code MenuSelectionManager}
  * to handle selection and navigation in menu hierarchies.
  *
  * @author Arnaud Weber
@@ -39,46 +39,56 @@
 public interface MenuElement {
 
     /**
-     * Processes a mouse event. <code>event</code> is a <code>MouseEvent</code>
-     * with source being the receiving element's component.
-     * <code>path</code> is the path of the receiving element in the menu
-     * hierarchy including the receiving element itself.
-     * <code>manager</code> is the <code>MenuSelectionManager</code>
-     * for the menu hierarchy.
-     * This method should process the <code>MouseEvent</code> and change
-     * the menu selection if necessary
-     * by using <code>MenuSelectionManager</code>'s API
-     * Note: you do not have to forward the event to sub-components.
-     * This is done automatically by the <code>MenuSelectionManager</code>.
+     * Processes a mouse event. {@code event} is a {@code MouseEvent} with
+     * source being the receiving element's component. {@code path} is the
+     * path of the receiving element in the menu hierarchy including the
+     * receiving element itself. {@code manager} is the
+     * {@code MenuSelectionManager}for the menu hierarchy. This method should
+     * process the {@code MouseEvent} and change the menu selection if necessary
+     * by using {@code MenuSelectionManager}'s API Note: you do not have to
+     * forward the event to sub-components. This is done automatically by the
+     * {@code MenuSelectionManager}.
+     *
+     * @param event a {@code MouseEvent} to be processed
+     * @param path the path of the receiving element in the menu hierarchy
+     * @param manager the {@code MenuSelectionManager} for the menu hierarchy
      */
-    public void processMouseEvent(MouseEvent event,MenuElement path[],MenuSelectionManager manager);
+    public void processMouseEvent(MouseEvent event, MenuElement path[], MenuSelectionManager manager);
 
 
     /**
      *  Process a key event.
+     *
+     * @param event a {@code KeyEvent} to be processed
+     * @param path the path of the receiving element in the menu hierarchy
+     * @param manager the {@code MenuSelectionManager} for the menu hierarchy
      */
-    public void processKeyEvent(KeyEvent event,MenuElement path[],MenuSelectionManager manager);
+    public void processKeyEvent(KeyEvent event, MenuElement path[], MenuSelectionManager manager);
 
     /**
-     * Call by the <code>MenuSelectionManager</code> when the
-     * <code>MenuElement</code> is added or remove from
-     * the menu selection.
+     * Call by the {@code MenuSelectionManager} when the {@code MenuElement} is
+     * added or removed from the menu selection.
+     *
+     * @param isIncluded can be used to indicate if this {@code MenuElement} is
+     *        active (if it is a menu) or is on the part of the menu path that
+     *        changed (if it is a menu item).
      */
     public void menuSelectionChanged(boolean isIncluded);
 
     /**
-     * This method should return an array containing the sub-elements for the receiving menu element
+     * This method should return an array containing the sub-elements for the
+     * receiving menu element.
      *
-     * @return an array of MenuElements
+     * @return an array of {@code MenuElement}s
      */
     public MenuElement[] getSubElements();
 
     /**
-     * This method should return the java.awt.Component used to paint the receiving element.
-     * The returned component will be used to convert events and detect if an event is inside
-     * a MenuElement's component.
+     * This method should return the {@code java.awt.Component} used to paint the
+     * receiving element. The returned component will be used to convert events
+     * and detect if an event is inside a {@code MenuElement}'s component.
      *
-     * @return the Component value
+     * @return the {@code Component} value
      */
     public Component getComponent();
 }
--- a/src/share/classes/javax/swing/MenuSelectionManager.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/MenuSelectionManager.java	Fri Jul 04 12:56:58 2014 +0400
@@ -80,6 +80,7 @@
      * generated is always "this".
      */
     protected transient ChangeEvent changeEvent = null;
+    /** The collection of registered listeners */
     protected EventListenerList listenerList = new EventListenerList();
 
     /**
@@ -477,7 +478,11 @@
     }
 
     /**
-     * Return true if c is part of the currently used menu
+     * Return true if {@code c} is part of the currently used menu
+     *
+     * @param c a {@code Component}
+     * @return true if {@code c} is part of the currently used menu,
+     *         false otherwise
      */
     public boolean isComponentPartOfCurrentMenu(Component c) {
         if(selection.size() > 0) {
--- a/src/share/classes/javax/swing/RowFilter.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/RowFilter.java	Fri Jul 04 12:56:58 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 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
@@ -159,6 +159,8 @@
      * {@link java.util.regex.Pattern} for a complete description of
      * the supported regular-expression constructs.
      *
+     * @param <M> the type of the model to which the {@code RowFilter} applies
+     * @param <I> the type of the identifier passed to the {@code RowFilter}
      * @param regex the regular expression to filter on
      * @param indices the indices of the values to check.  If not supplied all
      *               values are evaluated
@@ -186,6 +188,8 @@
      *   RowFilter.dateFilter(ComparisonType.AFTER, new Date());
      * </pre>
      *
+     * @param <M> the type of the model to which the {@code RowFilter} applies
+     * @param <I> the type of the identifier passed to the {@code RowFilter}
      * @param type the type of comparison to perform
      * @param date the date to compare against
      * @param indices the indices of the values to check.  If not supplied all
@@ -214,7 +218,10 @@
      *   RowFilter.numberFilter(ComparisonType.EQUAL, 10);
      * </pre>
      *
+     * @param <M> the type of the model to which the {@code RowFilter} applies
+     * @param <I> the type of the identifier passed to the {@code RowFilter}
      * @param type the type of comparison to perform
+     * @param number a {@code Number} value to compare against
      * @param indices the indices of the values to check.  If not supplied all
      *               values are evaluated
      * @return a <code>RowFilter</code> implementing the specified criteria
@@ -241,6 +248,8 @@
      *   RowFilter&lt;Object,Object&gt; fooBarFilter = RowFilter.orFilter(filters);
      * </pre>
      *
+     * @param <M> the type of the model to which the {@code RowFilter} applies
+     * @param <I> the type of the identifier passed to the {@code RowFilter}
      * @param filters the <code>RowFilter</code>s to test
      * @throws IllegalArgumentException if any of the filters
      *         are <code>null</code>
@@ -267,6 +276,8 @@
      *   RowFilter&lt;Object,Object&gt; fooBarFilter = RowFilter.andFilter(filters);
      * </pre>
      *
+     * @param <M> the type of the model the {@code RowFilter} applies to
+     * @param <I> the type of the identifier passed to the {@code RowFilter}
      * @param filters the <code>RowFilter</code>s to test
      * @return a <code>RowFilter</code> implementing the specified criteria
      * @throws IllegalArgumentException if any of the filters
@@ -283,6 +294,8 @@
      * Returns a <code>RowFilter</code> that includes entries if the
      * supplied filter does not include the entry.
      *
+     * @param <M> the type of the model to which the {@code RowFilter} applies
+     * @param <I> the type of the identifier passed to the {@code RowFilter}
      * @param filter the <code>RowFilter</code> to negate
      * @return a <code>RowFilter</code> implementing the specified criteria
      * @throws IllegalArgumentException if <code>filter</code> is
--- a/src/share/classes/javax/swing/SortingFocusTraversalPolicy.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/SortingFocusTraversalPolicy.java	Fri Jul 04 12:56:58 2014 +0400
@@ -100,6 +100,8 @@
 
     /**
      * Constructs a SortingFocusTraversalPolicy with the specified Comparator.
+     *
+     * @param comparator the {@code Comparator} to sort by
      */
     public SortingFocusTraversalPolicy(Comparator<? super Component> comparator) {
         this.comparator = comparator;
--- a/src/share/classes/javax/swing/Spring.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/Spring.java	Fri Jul 04 12:56:58 2014 +0400
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 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
@@ -547,9 +547,10 @@
 
 
     /**
-     * Returns <code>-s</code>: a spring running in the opposite direction to <code>s</code>.
+     * Returns {@code -s}: a spring running in the opposite direction to {@code s}.
      *
-     * @return <code>-s</code>: a spring running in the opposite direction to <code>s</code>
+     * @param s a {@code Spring} object
+     * @return {@code -s}: a spring running in the opposite direction to {@code s}
      *
      * @see Spring
      */
@@ -582,6 +583,8 @@
      * the <em>value</em>s of <code>s1</code> and <code>s2</code> is exactly equal to
      * the <em>value</em> of <code>s3</code>.
      *
+     * @param s1 a {@code Spring} object
+     * @param s2 a {@code Spring} object
      * @return <code>s1+s2</code>: a spring representing <code>s1</code> and <code>s2</code> in series
      *
      * @see Spring
@@ -591,11 +594,13 @@
      }
 
     /**
-     * Returns <code>max(s1, s2)</code>: a spring whose value is always greater than (or equal to)
-     *         the values of both <code>s1</code> and <code>s2</code>.
+     * Returns {@code max(s1, s2)}: a spring whose value is always greater than (or equal to)
+     *         the values of both {@code s1} and {@code s2}.
      *
-     * @return <code>max(s1, s2)</code>: a spring whose value is always greater than (or equal to)
-     *         the values of both <code>s1</code> and <code>s2</code>
+     * @param s1 a {@code Spring} object
+     * @param s2 a {@code Spring} object
+     * @return {@code max(s1, s2)}: a spring whose value is always greater than (or equal to)
+     *         the values of both {@code s1} and {@code s2}
      * @see Spring
      */
     public static Spring max(Spring s1, Spring s2) {
--- a/src/share/classes/javax/swing/UIManager.java	Thu Jul 03 16:19:39 2014 -0700
+++ b/src/share/classes/javax/swing/UIManager.java	Fri Jul 04 12:56:58 2014 +0400
@@ -1107,6 +1107,8 @@
      * UI class is created or when the default look and feel is changed
      * on a component instance.
      * <p>Note these are not the same as the installed look and feels.
+     *
+     * @param laf the {@code LookAndFeel} to be removed
      * @return true if the <code>LookAndFeel</code> was removed from the list
      * @see #removeAuxiliaryLookAndFeel
      * @see #getAuxiliaryLookAndFeels