From 8dac0497899cc0680fae8d6f1f6d75933cb0950b Mon Sep 17 00:00:00 2001
From: Steven Sides <steve.sides@oracle.com>
Date: Fri, 4 Jul 2014 12:56:58 +0400
Subject: [PATCH] 8046590: fix doclint issues in swing classes, part 1 of 4

Reviewed-by: alexsch
---
 .../javax/swing/AbstractListModel.java        |  1 +
 .../classes/javax/swing/CellRendererPane.java |  4 ++
 .../javax/swing/DefaultCellEditor.java        |  1 +
 .../javax/swing/DefaultDesktopManager.java    | 21 ++++--
 .../classes/javax/swing/DefaultListModel.java |  1 +
 .../swing/DefaultListSelectionModel.java      |  6 ++
 .../classes/javax/swing/DefaultRowSorter.java |  4 +-
 .../share/classes/javax/swing/InputMap.java   | 70 +++++++++++--------
 .../share/classes/javax/swing/JCheckBox.java  |  1 +
 .../javax/swing/JCheckBoxMenuItem.java        |  9 +--
 .../classes/javax/swing/JEditorPane.java      |  9 +--
 .../classes/javax/swing/JFileChooser.java     | 36 +++++++++-
 jdk/src/share/classes/javax/swing/JFrame.java |  6 +-
 jdk/src/share/classes/javax/swing/JMenu.java  | 34 +++++----
 .../share/classes/javax/swing/JMenuBar.java   |  4 +-
 .../share/classes/javax/swing/JSlider.java    |  4 ++
 .../classes/javax/swing/JTabbedPane.java      |  7 ++
 jdk/src/share/classes/javax/swing/JTable.java | 19 ++++-
 .../classes/javax/swing/MenuElement.java      | 58 ++++++++-------
 .../javax/swing/MenuSelectionManager.java     |  7 +-
 .../share/classes/javax/swing/RowFilter.java  | 15 +++-
 .../swing/SortingFocusTraversalPolicy.java    |  2 +
 jdk/src/share/classes/javax/swing/Spring.java | 19 +++--
 .../share/classes/javax/swing/UIManager.java  |  2 +
 24 files changed, 247 insertions(+), 93 deletions(-)

diff --git a/jdk/src/share/classes/javax/swing/AbstractListModel.java b/jdk/src/share/classes/javax/swing/AbstractListModel.java
index cc3003dc132..e4956670ee0 100644
--- a/jdk/src/share/classes/javax/swing/AbstractListModel.java
+++ b/jdk/src/share/classes/javax/swing/AbstractListModel.java
@@ -202,6 +202,7 @@ public abstract class AbstractListModel<E> implements ListModel<E>, Serializable
      * 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>
diff --git a/jdk/src/share/classes/javax/swing/CellRendererPane.java b/jdk/src/share/classes/javax/swing/CellRendererPane.java
index 70ba2afa04c..6050693eeeb 100644
--- a/jdk/src/share/classes/javax/swing/CellRendererPane.java
+++ b/jdk/src/share/classes/javax/swing/CellRendererPane.java
@@ -190,8 +190,12 @@ public class CellRendererPane extends Container implements Accessible
 // 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
diff --git a/jdk/src/share/classes/javax/swing/DefaultCellEditor.java b/jdk/src/share/classes/javax/swing/DefaultCellEditor.java
index ba8942c5b21..dfb9056e62c 100644
--- a/jdk/src/share/classes/javax/swing/DefaultCellEditor.java
+++ b/jdk/src/share/classes/javax/swing/DefaultCellEditor.java
@@ -353,6 +353,7 @@ public class DefaultCellEditor extends AbstractCellEditor
         * 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;
diff --git a/jdk/src/share/classes/javax/swing/DefaultDesktopManager.java b/jdk/src/share/classes/javax/swing/DefaultDesktopManager.java
index 6c66c8d6cce..ebee71521d9 100644
--- a/jdk/src/share/classes/javax/swing/DefaultDesktopManager.java
+++ b/jdk/src/share/classes/javax/swing/DefaultDesktopManager.java
@@ -462,7 +462,12 @@ public class DefaultDesktopManager implements DesktopManager, java.io.Serializab
         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 @@ public class DefaultDesktopManager implements DesktopManager, java.io.Serializab
         }
     }
 
-    /** 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 @@ public class DefaultDesktopManager implements DesktopManager, java.io.Serializab
     /**
      * 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) {
diff --git a/jdk/src/share/classes/javax/swing/DefaultListModel.java b/jdk/src/share/classes/javax/swing/DefaultListModel.java
index 2b10f45ad47..a4a826a0f5c 100644
--- a/jdk/src/share/classes/javax/swing/DefaultListModel.java
+++ b/jdk/src/share/classes/javax/swing/DefaultListModel.java
@@ -444,6 +444,7 @@ public class DefaultListModel<E> extends AbstractListModel<E>
      * (<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);
diff --git a/jdk/src/share/classes/javax/swing/DefaultListSelectionModel.java b/jdk/src/share/classes/javax/swing/DefaultListSelectionModel.java
index a1cb79f8ea6..671b1a412f0 100644
--- a/jdk/src/share/classes/javax/swing/DefaultListSelectionModel.java
+++ b/jdk/src/share/classes/javax/swing/DefaultListSelectionModel.java
@@ -160,6 +160,9 @@ public class DefaultListSelectionModel implements ListSelectionModel, Cloneable,
      * 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 @@ public class DefaultListSelectionModel implements ListSelectionModel, Cloneable,
      * 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 @@ public class DefaultListSelectionModel implements ListSelectionModel, Cloneable,
 
     /**
      * Sets the value of the leadAnchorNotificationEnabled flag.
+     *
+     * @param flag boolean value for {@code leadAnchorNotificationEnabled}
      * @see             #isLeadAnchorNotificationEnabled()
      */
     public void setLeadAnchorNotificationEnabled(boolean flag) {
diff --git a/jdk/src/share/classes/javax/swing/DefaultRowSorter.java b/jdk/src/share/classes/javax/swing/DefaultRowSorter.java
index 5b9e94537fe..68264dc89f0 100644
--- a/jdk/src/share/classes/javax/swing/DefaultRowSorter.java
+++ b/jdk/src/share/classes/javax/swing/DefaultRowSorter.java
@@ -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 @@ public abstract class DefaultRowSorter<M, I> extends RowSorter<M> {
      *
      * @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) {
diff --git a/jdk/src/share/classes/javax/swing/InputMap.java b/jdk/src/share/classes/javax/swing/InputMap.java
index 55af730c99a..87302b0b6e2 100644
--- a/jdk/src/share/classes/javax/swing/InputMap.java
+++ b/jdk/src/share/classes/javax/swing/InputMap.java
@@ -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.HashMap;
 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 @@ public class InputMap implements Serializable {
 
 
     /**
-     * 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 @@ public class InputMap implements Serializable {
     }
 
     /**
-     * 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 @@ public class InputMap implements Serializable {
     }
 
     /**
-     * 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 @@ public class InputMap implements Serializable {
     }
 
     /**
-     * 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 @@ public class InputMap implements Serializable {
     }
 
     /**
-     * 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 @@ public class InputMap implements Serializable {
     }
 
     /**
-     * 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 @@ public class InputMap implements Serializable {
     }
 
     /**
-     * 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();
diff --git a/jdk/src/share/classes/javax/swing/JCheckBox.java b/jdk/src/share/classes/javax/swing/JCheckBox.java
index c912a383cae..400b8efae78 100644
--- a/jdk/src/share/classes/javax/swing/JCheckBox.java
+++ b/jdk/src/share/classes/javax/swing/JCheckBox.java
@@ -132,6 +132,7 @@ public class JCheckBox extends JToggleButton implements Accessible {
      * 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) {
diff --git a/jdk/src/share/classes/javax/swing/JCheckBoxMenuItem.java b/jdk/src/share/classes/javax/swing/JCheckBoxMenuItem.java
index 962ef73f3c0..4aaa4417caa 100644
--- a/jdk/src/share/classes/javax/swing/JCheckBoxMenuItem.java
+++ b/jdk/src/share/classes/javax/swing/JCheckBoxMenuItem.java
@@ -109,7 +109,7 @@ public class JCheckBoxMenuItem extends JMenuItem implements SwingConstants,
     /**
      * 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 @@ public class JCheckBoxMenuItem extends JMenuItem implements SwingConstants,
     /**
      * 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 @@ public class JCheckBoxMenuItem extends JMenuItem implements SwingConstants,
      * 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 @@ public class JCheckBoxMenuItem extends JMenuItem implements SwingConstants,
     /**
      * 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);
diff --git a/jdk/src/share/classes/javax/swing/JEditorPane.java b/jdk/src/share/classes/javax/swing/JEditorPane.java
index d650c4816e8..42951731ec1 100644
--- a/jdk/src/share/classes/javax/swing/JEditorPane.java
+++ b/jdk/src/share/classes/javax/swing/JEditorPane.java
@@ -1251,11 +1251,12 @@ public class JEditorPane extends JTextComponent {
     }
 
     /**
-     * Returns the currently registered <code>EditorKit</code>
-     * class name for the type <code>type</code>.
-     *
-     * @param type  the non-<code>null</code> content type
+     * Returns the currently registered {@code EditorKit} class name for the
+     * type {@code 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) {
diff --git a/jdk/src/share/classes/javax/swing/JFileChooser.java b/jdk/src/share/classes/javax/swing/JFileChooser.java
index 336f57c438b..bf690ddbb5b 100644
--- a/jdk/src/share/classes/javax/swing/JFileChooser.java
+++ b/jdk/src/share/classes/javax/swing/JFileChooser.java
@@ -330,6 +330,8 @@ public class JFileChooser extends JComponent implements Accessible {
     /**
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
     /**
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
     /**
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
 
     /**
      * Performs common constructor initialization and setup.
+     *
+     * @param view the {@code FileSystemView} used for setup
      */
     protected void setup(FileSystemView view) {
         installShowFilesListener();
@@ -512,6 +524,8 @@ public class JFileChooser extends JComponent implements Accessible {
     /**
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
     /**
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
     /**
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
     * 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 @@ public class JFileChooser extends JComponent implements Accessible {
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
     }
 
     /**
-     * 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 @@ public class JFileChooser extends JComponent implements Accessible {
     /**
      * Returns the current file view.
      *
+     * @return the current file view
      * @see #setFileView
      */
     public FileView getFileView() {
@@ -1765,6 +1792,8 @@ public class JFileChooser extends JComponent implements Accessible {
      * 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 @@ public class JFileChooser extends JComponent implements Accessible {
 // Accessibility support
 ////////////////
 
+    /**
+     * {@code AccessibleContext} associated with this {@code JFileChooser}
+     */
     protected AccessibleContext accessibleContext = null;
 
     /**
diff --git a/jdk/src/share/classes/javax/swing/JFrame.java b/jdk/src/share/classes/javax/swing/JFrame.java
index e4a5efef662..cc3b0807f96 100644
--- a/jdk/src/share/classes/javax/swing/JFrame.java
+++ b/jdk/src/share/classes/javax/swing/JFrame.java
@@ -275,6 +275,8 @@ public class JFrame  extends Frame implements WindowConstants,
     /**
      * 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 @@ public class JFrame  extends Frame implements WindowConstants,
 // Accessibility support
 ////////////////
 
-    /** The accessible context property. */
+    /**
+     * The accessible context property.
+     */
     protected AccessibleContext accessibleContext = null;
 
     /**
diff --git a/jdk/src/share/classes/javax/swing/JMenu.java b/jdk/src/share/classes/javax/swing/JMenu.java
index ea3b1b970d3..02285e0047f 100644
--- a/jdk/src/share/classes/javax/swing/JMenu.java
+++ b/jdk/src/share/classes/javax/swing/JMenu.java
@@ -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 @@ public class JMenu extends JMenuItem implements Accessible,MenuElement
      * 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 @@ public class JMenu extends JMenuItem implements Accessible,MenuElement
     }
 
     /**
-     * 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 @@ public class JMenu extends JMenuItem implements Accessible,MenuElement
      * @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 @@ public class JMenu extends JMenuItem implements Accessible,MenuElement
     }
 
     /**
-     * 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 @@ public class JMenu extends JMenuItem implements Accessible,MenuElement
     /**
      * 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 @@ public class JMenu extends JMenuItem implements Accessible,MenuElement
         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) {
diff --git a/jdk/src/share/classes/javax/swing/JMenuBar.java b/jdk/src/share/classes/javax/swing/JMenuBar.java
index 4b4f6f91643..c8fcb6673c6 100644
--- a/jdk/src/share/classes/javax/swing/JMenuBar.java
+++ b/jdk/src/share/classes/javax/swing/JMenuBar.java
@@ -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 @@ public class JMenuBar extends JComponent implements Accessible,MenuElement
 
     /**
      * 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() {
diff --git a/jdk/src/share/classes/javax/swing/JSlider.java b/jdk/src/share/classes/javax/swing/JSlider.java
index 09129a479f0..a2524d9b244 100644
--- a/jdk/src/share/classes/javax/swing/JSlider.java
+++ b/jdk/src/share/classes/javax/swing/JSlider.java
@@ -281,6 +281,8 @@ public class JSlider extends JComponent implements SwingConstants, Accessible {
     /**
      * Creates a horizontal slider using the specified
      * BoundedRangeModel.
+     *
+     * @param brm a {@code BoundedRangeModel} for the slider
      */
     public JSlider(BoundedRangeModel brm)
     {
@@ -363,6 +365,8 @@ public class JSlider extends JComponent implements SwingConstants, Accessible {
      * {@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
diff --git a/jdk/src/share/classes/javax/swing/JTabbedPane.java b/jdk/src/share/classes/javax/swing/JTabbedPane.java
index c3b135ac85e..96c050529fe 100644
--- a/jdk/src/share/classes/javax/swing/JTabbedPane.java
+++ b/jdk/src/share/classes/javax/swing/JTabbedPane.java
@@ -278,6 +278,7 @@ public class JTabbedPane extends JComponent
      * 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 @@ public class JTabbedPane extends JComponent
     /**
      * Returns the model associated with this tabbedpane.
      *
+     * @return the {@code SingleSelectionModel} associated with this tabbedpane
      * @see #setModel
      */
     public SingleSelectionModel getModel() {
@@ -459,6 +461,8 @@ public class JTabbedPane extends JComponent
 
     /**
      * 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 @@ public class JTabbedPane extends JComponent
     /**
      * 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 @@ public class JTabbedPane extends JComponent
      * 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
diff --git a/jdk/src/share/classes/javax/swing/JTable.java b/jdk/src/share/classes/javax/swing/JTable.java
index f4573926a95..1c7f72c947d 100644
--- a/jdk/src/share/classes/javax/swing/JTable.java
+++ b/jdk/src/share/classes/javax/swing/JTable.java
@@ -865,6 +865,8 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
     /**
      * 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 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
      * <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 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
      * 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 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
 
     /**
      * 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 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
 
     // Listeners to echo changes to the AccessiblePropertyChange mechanism
 
-        /*
+        /**
          * Describes a change in the accessible table model.
          */
         protected class AccessibleJTableModelChange
@@ -6737,6 +6743,8 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
 
         /**
          * 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 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
 
         /**
          * 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 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
 
         /**
          * 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 @@ public class JTable extends JComponent implements TableModelListener, Scrollable
 
             /**
              *  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) {
diff --git a/jdk/src/share/classes/javax/swing/MenuElement.java b/jdk/src/share/classes/javax/swing/MenuElement.java
index 916811e08eb..4dc310b55bc 100644
--- a/jdk/src/share/classes/javax/swing/MenuElement.java
+++ b/jdk/src/share/classes/javax/swing/MenuElement.java
@@ -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 @@ import java.awt.event.*;
 
 /**
  * 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 @@ import java.awt.event.*;
 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();
 }
diff --git a/jdk/src/share/classes/javax/swing/MenuSelectionManager.java b/jdk/src/share/classes/javax/swing/MenuSelectionManager.java
index 8a691c1b9cd..dda2736eb49 100644
--- a/jdk/src/share/classes/javax/swing/MenuSelectionManager.java
+++ b/jdk/src/share/classes/javax/swing/MenuSelectionManager.java
@@ -80,6 +80,7 @@ public class MenuSelectionManager {
      * generated is always "this".
      */
     protected transient ChangeEvent changeEvent = null;
+    /** The collection of registered listeners */
     protected EventListenerList listenerList = new EventListenerList();
 
     /**
@@ -477,7 +478,11 @@ public class MenuSelectionManager {
     }
 
     /**
-     * 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) {
diff --git a/jdk/src/share/classes/javax/swing/RowFilter.java b/jdk/src/share/classes/javax/swing/RowFilter.java
index 8201add8bdc..bdcdb15786b 100644
--- a/jdk/src/share/classes/javax/swing/RowFilter.java
+++ b/jdk/src/share/classes/javax/swing/RowFilter.java
@@ -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 @@ public abstract class RowFilter<M,I> {
      * {@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 @@ public abstract class RowFilter<M,I> {
      *   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 @@ public abstract class RowFilter<M,I> {
      *   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 @@ public abstract class RowFilter<M,I> {
      *   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 @@ public abstract class RowFilter<M,I> {
      *   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 @@ public abstract class RowFilter<M,I> {
      * 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
diff --git a/jdk/src/share/classes/javax/swing/SortingFocusTraversalPolicy.java b/jdk/src/share/classes/javax/swing/SortingFocusTraversalPolicy.java
index 2c4850b8ff4..c542ebc48f8 100644
--- a/jdk/src/share/classes/javax/swing/SortingFocusTraversalPolicy.java
+++ b/jdk/src/share/classes/javax/swing/SortingFocusTraversalPolicy.java
@@ -100,6 +100,8 @@ public class SortingFocusTraversalPolicy
 
     /**
      * Constructs a SortingFocusTraversalPolicy with the specified Comparator.
+     *
+     * @param comparator the {@code Comparator} to sort by
      */
     public SortingFocusTraversalPolicy(Comparator<? super Component> comparator) {
         this.comparator = comparator;
diff --git a/jdk/src/share/classes/javax/swing/Spring.java b/jdk/src/share/classes/javax/swing/Spring.java
index 75b2a510f00..366b95fec78 100644
--- a/jdk/src/share/classes/javax/swing/Spring.java
+++ b/jdk/src/share/classes/javax/swing/Spring.java
@@ -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 @@ public abstract class Spring {
 
 
     /**
-     * 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 @@ public abstract class Spring {
      * 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 @@ public abstract class Spring {
      }
 
     /**
-     * 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) {
diff --git a/jdk/src/share/classes/javax/swing/UIManager.java b/jdk/src/share/classes/javax/swing/UIManager.java
index 951d0f6c239..27f243b4d6c 100644
--- a/jdk/src/share/classes/javax/swing/UIManager.java
+++ b/jdk/src/share/classes/javax/swing/UIManager.java
@@ -1107,6 +1107,8 @@ public class UIManager implements Serializable
      * 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