8046597: fix doclint issues in swing classes, part 4 of 4

Reviewed-by: pchelko

jdk/src/share/classes/javax/swing/AbstractAction.java

@@ -269,6 +269,10 @@ public abstract class AbstractAction implements Action, Cloneable, Serializable
      * when a bound property has changed and it will send the appropriate
      * <code>PropertyChangeEvent</code> to any registered
      * <code>PropertyChangeListeners</code>.
+     *
+     * @param propertyName  the name of the property that has changed
+     * @param oldValue  the old value of the property
+     * @param newValue  the new value of the property
      */
     protected void firePropertyChange(String propertyName, Object oldValue, Object newValue) {
         if (changeSupport == null ||

jdk/src/share/classes/javax/swing/CellRendererPane.java

@@ -120,6 +120,18 @@ public class CellRendererPane extends Container implements Accessible
      * The Container p is the component we're actually drawing on, typically it's
      * equal to this.getParent(). If shouldValidate is true the component c will be
      * validated before painted.
+     *
+     * @param g  the {@code Graphics} object to draw on
+     * @param c  the {@code Component} to draw
+     * @param p  the {@code Container} component actually drawn on
+     * @param x  an int specifying the left side of the area draw in, in pixels,
+     *           measured from the left edge of the graphics context
+     * @param y  an int specifying the top of the area to draw in, in pixels
+     *           measured down from the top edge of the graphics context
+     * @param w  an int specifying the width of the area draw in, in pixels
+     * @param h  an int specifying the height of the area draw in, in pixels
+     * @param shouldValidate  if true, component {@code c} will be validated
+     *                        before being painted
      */
     public void paintComponent(Graphics g, Component c, Container p, int x, int y, int w, int h, boolean shouldValidate) {
         if (c == null) {
@@ -166,6 +178,16 @@ public class CellRendererPane extends Container implements Accessible
 
     /**
      * Calls this.paintComponent(g, c, p, x, y, w, h, false).
+     *
+     * @param g  the {@code Graphics} object to draw on
+     * @param c  the {@code Component} to draw
+     * @param p  the {@code Container} component actually drawn on
+     * @param x  an int specifying the left side of the area draw in, in pixels,
+     *           measured from the left edge of the graphics context
+     * @param y  an int specifying the top of the area to draw in, in pixels
+     *           measured down from the top edge of the graphics context
+     * @param w  an int specifying the width of the area draw in, in pixels
+     * @param h  an int specifying the height of the area draw in, in pixels
      */
     public void paintComponent(Graphics g, Component c, Container p, int x, int y, int w, int h) {
         paintComponent(g, c, p, x, y, w, h, false);
@@ -174,6 +196,11 @@ public class CellRendererPane extends Container implements Accessible
 
     /**
      * Calls this.paintComponent() with the rectangles x,y,width,height fields.
+     *
+     * @param g  the {@code Graphics} object to draw on
+     * @param c  the {@code Component} to draw
+     * @param p  the {@code Container} component actually drawn on
+     * @param r  the {@code Rectangle} to draw in
      */
     public void paintComponent(Graphics g, Component c, Container p, Rectangle r) {
         paintComponent(g, c, p, r.x, r.y, r.width, r.height);

jdk/src/share/classes/javax/swing/DebugGraphics.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2010, 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
@@ -139,6 +139,8 @@ public class DebugGraphics extends Graphics {
 
     /**
      * Sets the Color used to flash drawing operations.
+     *
+     * @param flashColor the Color used to flash drawing operations
      */
     public static void setFlashColor(Color flashColor) {
         info().flashColor = flashColor;
@@ -146,6 +148,8 @@ public class DebugGraphics extends Graphics {
 
     /**
      * Returns the Color used to flash drawing operations.
+     *
+     * @return the Color used to flash drawing operations
      * @see #setFlashColor
      */
     public static Color flashColor() {
@@ -154,6 +158,8 @@ public class DebugGraphics extends Graphics {
 
     /**
      * Sets the time delay of drawing operation flashing.
+     *
+     * @param flashTime the time delay of drawing operation flashing
      */
     public static void setFlashTime(int flashTime) {
         info().flashTime = flashTime;
@@ -161,6 +167,8 @@ public class DebugGraphics extends Graphics {
 
     /**
      * Returns the time delay of drawing operation flashing.
+     *
+     * @return the time delay of drawing operation flashing
      * @see #setFlashTime
      */
     public static int flashTime() {
@@ -169,27 +177,38 @@ public class DebugGraphics extends Graphics {
 
     /**
      * Sets the number of times that drawing operations will flash.
+     *
+     * @param flashCount number of times that drawing operations will flash
      */
     public static void setFlashCount(int flashCount) {
         info().flashCount = flashCount;
     }
 
-    /** Returns the number of times that drawing operations will flash.
+    /**
-      * @see #setFlashCount
+     * Returns the number of times that drawing operations will flash.
-      */
+     *
+     * @return the number of times that drawing operations will flash
+     * @see #setFlashCount
+     */
     public static int flashCount() {
         return info().flashCount;
     }
 
-    /** Sets the stream to which the DebugGraphics logs drawing operations.
+    /**
-      */
+     * Sets the stream to which the DebugGraphics logs drawing operations.
+     *
+     * @param stream the stream to which the DebugGraphics logs drawing operations
+     */
     public static void setLogStream(java.io.PrintStream stream) {
         info().stream = stream;
     }
 
-    /** Returns the stream to which the DebugGraphics logs drawing operations.
+    /**
-      * @see #setLogStream
+     * Returns the stream to which the DebugGraphics logs drawing operations.
-      */
+     *
+     * @return the stream to which the DebugGraphics logs drawing operations
+     * @see #setLogStream
+     */
     public static java.io.PrintStream logStream() {
         return info().stream;
     }
@@ -1337,6 +1356,8 @@ public class DebugGraphics extends Graphics {
       * creates a new Frame that shows each operation on an
       * offscreen buffer. The value of <b>options</b> is bitwise OR'd into
       * the current value. To disable debugging use NONE_OPTION.
+      *
+      * @param options indicates how diagnostic information should be displayed
       */
     public void setDebugOptions(int options) {
         if (options != 0) {
@@ -1356,9 +1377,12 @@ public class DebugGraphics extends Graphics {
         }
     }
 
-    /** Returns the current debugging options for this DebugGraphics.
+    /**
-      * @see #setDebugOptions
+     * Returns the current debugging options for this DebugGraphics.
-      */
+     *
+     * @return the current debugging options for this DebugGraphics
+     * @see #setDebugOptions
+     */
     public int getDebugOptions() {
         return debugOptions;
     }

jdk/src/share/classes/javax/swing/DefaultBoundedRangeModel.java

@@ -88,6 +88,11 @@ public class DefaultBoundedRangeModel implements BoundedRangeModel, Serializable
      * <pre>
      * min &lt;= value &lt;= value+extent &lt;= max
      * </pre>
+     *
+     * @param value  an int giving the current value
+     * @param extent the length of the inner range that begins at the model's value
+     * @param min    an int giving the minimum value
+     * @param max    an int giving the maximum value
      */
     public DefaultBoundedRangeModel(int value, int extent, int min, int max)
     {
@@ -403,6 +408,7 @@ public class DefaultBoundedRangeModel implements BoundedRangeModel, 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>

jdk/src/share/classes/javax/swing/DefaultDesktopManager.java

@@ -71,7 +71,7 @@ public class DefaultDesktopManager implements DesktopManager, java.io.Serializab
     private transient boolean didDrag;
 
     /** Normally this method will not be called. If it is, it
-      * try to determine the appropriate parent from the desktopIcon of the frame.
+      * tries to determine the appropriate parent from the desktopIcon of the frame.
       * Will remove the desktopIcon from its parent if it successfully adds the frame.
       */
     public void openFrame(JInternalFrame f) {

jdk/src/share/classes/javax/swing/DefaultSingleSelectionModel.java

@@ -155,6 +155,7 @@ 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>

jdk/src/share/classes/javax/swing/DesktopManager.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
@@ -47,73 +47,136 @@ package javax.swing;
   */
 public interface DesktopManager
 {
-    /** If possible, display this frame in an appropriate location.
+    /**
-      * Normally, this is not called, as the creator of the JInternalFrame
+     * If possible, display this frame in an appropriate location.
-      * will add the frame to the appropriate parent.
+     * Normally, this is not called, as the creator of the JInternalFrame
-      */
+     * will add the frame to the appropriate parent.
+     *
+     * @param f  the {@code JInternalFrame} to be displayed
+     */
     void openFrame(JInternalFrame f);
 
-    /** Generally, this call should remove the frame from it's parent. */
+    /**
+     * Generally, this call should remove the frame from its parent.
+     *
+     * @param f  the {@code JInternalFrame} to be removed
+     */
     void closeFrame(JInternalFrame f);
 
-    /** Generally, the frame should be resized to match it's parents bounds. */
+    /**
+     * Generally, the frame should be resized to match its parents bounds.
+     *
+     * @param f  the {@code JInternalFrame} to be resized
+     */
     void maximizeFrame(JInternalFrame f);
-    /** Generally, this indicates that the frame should be restored to it's
+
-      * size and position prior to a maximizeFrame() call.
+    /**
-      */
+     * Generally, this indicates that the frame should be restored to its
+     * size and position prior to a maximizeFrame() call.
+     *
+     * @param f  the {@code JInternalFrame} to be restored
+     */
     void minimizeFrame(JInternalFrame f);
-    /** Generally, remove this frame from it's parent and add an iconic representation. */
+
+    /**
+     * Generally, remove this frame from its parent and add an iconic representation.
+     *
+     * @param f  the {@code JInternalFrame} to be iconified
+     */
     void iconifyFrame(JInternalFrame f);
-    /** Generally, remove any iconic representation that is present and restore the
+
-      * frame to it's original size and location.
+    /**
-      */
+     * Generally, remove any iconic representation that is present and restore the
+     * frame to it's original size and location.
+     *
+     * @param f  the {@code JInternalFrame} to be de-iconified
+     */
     void deiconifyFrame(JInternalFrame f);
 
     /**
      * Generally, indicate that this frame has focus. This is usually called after
      * the JInternalFrame's IS_SELECTED_PROPERTY has been set to true.
+     *
+     * @param f  the {@code JInternalFrame} to be activated
      */
     void activateFrame(JInternalFrame f);
 
     /**
      * Generally, indicate that this frame has lost focus. This is usually called
      * after the JInternalFrame's IS_SELECTED_PROPERTY has been set to false.
+     *
+     * @param f  the {@code JInternalFrame} to be deactivated
      */
     void deactivateFrame(JInternalFrame f);
 
-    /** This method is normally called when the user has indicated that
+    /**
-      * they will begin dragging a component around. This method should be called
+     * This method is normally called when the user has indicated that
-      * prior to any dragFrame() calls to allow the DesktopManager to prepare any
+     * they will begin dragging a component around. This method should be called
-      * necessary state. Normally <b>f</b> will be a JInternalFrame.
+     * prior to any dragFrame() calls to allow the DesktopManager to prepare any
-      */
+     * necessary state. Normally <b>f</b> will be a JInternalFrame.
+     *
+     * @param f  the {@code JComponent} being dragged
+     */
     void beginDraggingFrame(JComponent f);
 
-    /** The user has moved the frame. Calls to this method will be preceded by calls
+    /**
-      * to beginDraggingFrame().
+     * The user has moved the frame. Calls to this method will be preceded by calls
-      *  Normally <b>f</b> will be a JInternalFrame.
+     * to beginDraggingFrame().
-      */
+     * Normally <b>f</b> will be a JInternalFrame.
+     *
+     * @param f  the {@code JComponent} being dragged
+     * @param newX  the new x-coordinate
+     * @param newY  the new y-coordinate
+     */
     void dragFrame(JComponent f, int newX, int newY);
-    /** This method signals the end of the dragging session. Any state maintained by
+
-      * the DesktopManager can be removed here.  Normally <b>f</b> will be a JInternalFrame.
+    /**
-      */
+     * This method signals the end of the dragging session. Any state maintained by
+     * the DesktopManager can be removed here.  Normally <b>f</b> will be a JInternalFrame.
+     *
+     * @param f  the {@code JComponent} being dragged
+     */
     void endDraggingFrame(JComponent f);
 
-    /** This methods is normally called when the user has indicated that
+    /**
-      * they will begin resizing the frame. This method should be called
+     * This method is normally called when the user has indicated that
-      * prior to any resizeFrame() calls to allow the DesktopManager to prepare any
+     * they will begin resizing the frame. This method should be called
-      * necessary state.  Normally <b>f</b> will be a JInternalFrame.
+     * prior to any resizeFrame() calls to allow the DesktopManager to prepare any
-      */
+     * necessary state.  Normally <b>f</b> will be a JInternalFrame.
+     *
+     * @param f  the {@code JComponent} being resized
+     */
     void beginResizingFrame(JComponent f, int direction);
-    /** The user has resized the component. Calls to this method will be preceded by calls
+
-      * to beginResizingFrame().
+    /**
-      *  Normally <b>f</b> will be a JInternalFrame.
+     * The user has resized the component. Calls to this method will be preceded by calls
-      */
+     * to beginResizingFrame().
+     * Normally <b>f</b> will be a JInternalFrame.
+     *
+     * @param f  the {@code JComponent} being resized
+     * @param newX  the new x-coordinate
+     * @param newY  the new y-coordinate
+     * @param newWidth  the new width
+     * @param newHeight  the new height
+     */
     void resizeFrame(JComponent f, int newX, int newY, int newWidth, int newHeight);
-    /** This method signals the end of the resize session. Any state maintained by
+
-      * the DesktopManager can be removed here.  Normally <b>f</b> will be a JInternalFrame.
+    /**
-      */
+     * This method signals the end of the resize session. Any state maintained by
+     * the DesktopManager can be removed here.  Normally <b>f</b> will be a JInternalFrame.
+     *
+     * @param f  the {@code JComponent} being resized
+     */
     void endResizingFrame(JComponent f);
 
-    /** This is a primitive reshape method.*/
+    /**
+     * This is a primitive reshape method.
+     *
+     * @param f  the {@code JComponent} being moved or resized
+     * @param newX  the new x-coordinate
+     * @param newY  the new y-coordinate
+     * @param newWidth  the new width
+     * @param newHeight  the new height
+     */
     void setBoundsForFrame(JComponent f, int newX, int newY, int newWidth, int newHeight);
 }

jdk/src/share/classes/javax/swing/GrayFilter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 1998, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -44,6 +44,9 @@ public class GrayFilter extends RGBImageFilter {
 
     /**
      * Creates a disabled image
+     *
+     * @param i  an {@code Image} to be created as disabled
+     * @return  the new grayscale image created from {@code i}
      */
     public static Image createDisabledImage (Image i) {
         GrayFilter filter = new GrayFilter(true, 50);

jdk/src/share/classes/javax/swing/Icon.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 1998, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -41,6 +41,11 @@ public interface Icon
      * Draw the icon at the specified location.  Icon implementations
      * may use the Component argument to get properties useful for
      * painting, e.g. the foreground or background color.
+     *
+     * @param c  a {@code Component} to get properties useful for painting
+     * @param g  the graphics context
+     * @param x  the X coordinate of the icon's top-left corner
+     * @param y  the Y coordinate of the icon's top-left corner
      */
     void paintIcon(Component c, Graphics g, int x, int y);
 

jdk/src/share/classes/javax/swing/JApplet.java

@@ -157,8 +157,11 @@ public class JApplet extends Applet implements Accessible,
         enableEvents(AWTEvent.KEY_EVENT_MASK);
     }
 
-
+    /**
-    /** Called by the constructor methods to create the default rootPane. */
+     * Called by the constructor methods to create the default rootPane.
+     *
+     * @return  a new {@code JRootPane}
+     */
     protected JRootPane createRootPane() {
         JRootPane rp = new JRootPane();
         // NOTE: this uses setOpaque vs LookAndFeel.installProperty as there
@@ -247,6 +250,7 @@ public class JApplet extends Applet implements Accessible,
    /**
     * Returns the menubar set on this applet.
     *
+    * @return the menubar set on this applet
     * @see #setJMenuBar
     */
     public JMenuBar getJMenuBar() {
@@ -542,6 +546,9 @@ public class JApplet extends Applet implements Accessible,
 // Accessibility support
 ////////////////
 
+    /**
+     * {@code AccessibleContext} associated with this {@code JApplet}
+     */
     protected AccessibleContext accessibleContext = null;
 
     /**

jdk/src/share/classes/javax/swing/JComponent.java

@@ -496,6 +496,7 @@ public abstract class JComponent extends Container implements Serializable,
     /**
      * Returns true if the JPopupMenu should be inherited from the parent.
      *
+     * @return true if the JPopupMenu should be inherited from the parent
      * @see #setComponentPopupMenu
      * @since 1.5
      */
@@ -1302,6 +1303,7 @@ public abstract class JComponent extends Container implements Serializable,
      * <code>SortingFocusTraversalPolicy</code> from considering descendants
      * of this JComponent when computing a focus traversal cycle.
      *
+     * @return false
      * @see java.awt.Component#setFocusTraversalKeys
      * @see SortingFocusTraversalPolicy
      * @deprecated As of 1.4, replaced by
@@ -2213,6 +2215,13 @@ public abstract class JComponent extends Container implements Serializable,
      * This method is now obsolete, please use a combination of
      * <code>getActionMap()</code> and <code>getInputMap()</code> for
      * similar behavior.
+     *
+     * @param anAction  action to be registered to given keystroke and condition
+     * @param aKeyStroke  a {@code KeyStroke}
+     * @param aCondition  the condition to be associated with given keystroke
+     *                    and action
+     * @see #getActionMap
+     * @see #getInputMap(int)
      */
     public void registerKeyboardAction(ActionListener anAction,KeyStroke aKeyStroke,int aCondition) {
         registerKeyboardAction(anAction,null,aKeyStroke,aCondition);
@@ -2231,6 +2240,9 @@ public abstract class JComponent extends Container implements Serializable,
      * Unregisters a keyboard action.
      * This will remove the binding from the <code>ActionMap</code>
      * (if it exists) as well as the <code>InputMap</code>s.
+     *
+     * @param aKeyStroke  the keystroke for which to unregister its
+     *                    keyboard action
      */
     public void unregisterKeyboardAction(KeyStroke aKeyStroke) {
         ActionMap am = getActionMap(false);
@@ -2286,6 +2298,8 @@ public abstract class JComponent extends Container implements Serializable,
      * conditions <code>WHEN_FOCUSED</code> and
      * <code>WHEN_IN_FOCUSED_WINDOW</code> condition.
      *
+     * @param aKeyStroke  the keystroke for which to request an
+     *                    action-keystroke condition
      * @return the action-keystroke condition
      */
     public int getConditionForKeyStroke(KeyStroke aKeyStroke) {
@@ -2302,6 +2316,7 @@ public abstract class JComponent extends Container implements Serializable,
      * Returns the object that will perform the action registered for a
      * given keystroke.
      *
+     * @param aKeyStroke  the keystroke for which to return a listener
      * @return the <code>ActionListener</code>
      *          object invoked when the keystroke occurs
      */
@@ -2610,6 +2625,8 @@ public abstract class JComponent extends Container implements Serializable,
      * <code>FocusTraversalPolicy</code> of this <code>JComponent</code>'s
      * focus-cycle-root ancestor is used.
      *
+     * @return true if this component can request to get the input focus,
+     *              false if it can not
      * @see java.awt.FocusTraversalPolicy#getDefaultComponent
      * @deprecated As of 1.4, replaced by
      * <code>FocusTraversalPolicy.getDefaultComponent(Container).requestFocus()</code>
@@ -2821,6 +2838,8 @@ public abstract class JComponent extends Container implements Serializable,
      * normally override this method if they process some
      * key events themselves.  If the event is processed,
      * it should be consumed.
+     *
+     * @param e the event to be processed
      */
     protected void processComponentKeyEvent(KeyEvent e) {
     }
@@ -3032,6 +3051,10 @@ public abstract class JComponent extends Container implements Serializable,
      * <code>setToolTipText</code>.  If a component provides
      * more extensive API to support differing tooltips at different locations,
      * this method should be overridden.
+     *
+     * @param event the {@code MouseEvent} that initiated the
+     *              {@code ToolTip} display
+     * @return a string containing the  tooltip
      */
     public String getToolTipText(MouseEvent event) {
         return getToolTipText();
@@ -3774,6 +3797,10 @@ public abstract class JComponent extends Container implements Serializable,
          * but not very pretty outside borders in compound border situations.
          * It's rather arbitrary, but hopefully decent UI programmers will
          * not create multiple titled borders for the same component.
+         *
+         * @param b  the {@code Border} for which to retrieve its title
+         * @return the border's title as a {@code String}, null if it has
+         *         no title
          */
         protected String getBorderTitle(Border b) {
             String s;
@@ -4198,6 +4225,7 @@ public abstract class JComponent extends Container implements Serializable,
      * Returns true if this component is lightweight, that is, if it doesn't
      * have a native window system peer.
      *
+     * @param c  the {@code Component} to be checked
      * @return true if this component is lightweight
      */
     @SuppressWarnings("deprecation")

jdk/src/share/classes/javax/swing/JDesktopPane.java

@@ -208,8 +208,11 @@ public class JDesktopPane extends JLayeredPane implements Accessible
      }
 
     /**
-     * Returns the <code>DesktopManger</code> that handles
+     * Returns the {@code DesktopManger} that handles
      * desktop-specific UI actions.
+     *
+     * @return the {@code DesktopManger} that handles desktop-specific
+     *         UI actions
      */
     public DesktopManager getDesktopManager() {
         return desktopManager;

jdk/src/share/classes/javax/swing/JDialog.java

@@ -664,6 +664,8 @@ public class JDialog extends Dialog implements WindowConstants,
     /**
      * Called by the constructor methods to create the default
      * {@code rootPane}.
+     *
+     * @return  a new {@code JRootPane}
      */
     protected JRootPane createRootPane() {
         JRootPane rp = new JRootPane();
@@ -854,6 +856,7 @@ public class JDialog extends Dialog implements WindowConstants,
    /**
     * Returns the menubar set on this dialog.
     *
+    * @return the menubar set on this dialog
     * @see #setJMenuBar
     */
     public JMenuBar getJMenuBar() {
@@ -1225,6 +1228,9 @@ public class JDialog extends Dialog implements WindowConstants,
 // Accessibility support
 ////////////////
 
+    /**
+     * {@code AccessibleContext} associated with this {@code JDialog}
+     */
     protected AccessibleContext accessibleContext = null;
 
     /**

jdk/src/share/classes/javax/swing/JLabel.java

@@ -128,6 +128,10 @@ public class JLabel extends JComponent implements SwingConstants, Accessible
     private int horizontalTextPosition = TRAILING;
     private int iconTextGap = 4;
 
+    /**
+     * The Component this label is for; null if the label
+     * is not the label for a component
+     */
     protected Component labelFor = null;
 
     /**
@@ -310,6 +314,7 @@ public class JLabel extends JComponent implements SwingConstants, Accessible
      * <p>
      * This is a JavaBeans bound property.
      *
+     * @param text  the single line of text this component will display
      * @see #setVerticalTextPosition
      * @see #setHorizontalTextPosition
      * @see #setIcon
@@ -366,6 +371,7 @@ public class JLabel extends JComponent implements SwingConstants, Accessible
      * <p>
      * This is a JavaBeans bound property.
      *
+     * @param icon  the default icon this component will display
      * @see #setVerticalTextPosition
      * @see #setHorizontalTextPosition
      * @see #getIcon
@@ -476,6 +482,7 @@ public class JLabel extends JComponent implements SwingConstants, Accessible
      * call the requestFocus method of the component specified by the
      * labelFor property when the mnemonic is activated.
      *
+     * @param key  a keycode that indicates a mnemonic key
      * @see #getLabelFor
      * @see #setLabelFor
      * @beaninfo
@@ -592,6 +599,8 @@ public class JLabel extends JComponent implements SwingConstants, Accessible
      *
      * @param key the property value to check
      * @param message the IllegalArgumentException detail message
+     * @return the key value if {@code key} is a a legal value for the
+     *         horizontalAlignment properties
      * @exception IllegalArgumentException if key isn't LEFT, CENTER, RIGHT,
      * LEADING or TRAILING.
      * @see #setHorizontalTextPosition
@@ -617,6 +626,8 @@ public class JLabel extends JComponent implements SwingConstants, Accessible
      *
      * @param key the property value to check
      * @param message the IllegalArgumentException detail message
+     * @return the key value if {@code key} is a legal value for the
+     *         verticalAlignment or verticalTextPosition properties
      * @exception IllegalArgumentException if key isn't TOP, CENTER, or BOTTOM.
      * @see #setVerticalAlignment
      * @see #setVerticalTextPosition
@@ -652,6 +663,7 @@ public class JLabel extends JComponent implements SwingConstants, Accessible
      * <p>
      * This is a JavaBeans bound property.
      *
+     * @param iconTextGap  the space between the icon and text properties
      * @see #getIconTextGap
      * @beaninfo
      *        bound: true

jdk/src/share/classes/javax/swing/JPopupMenu.java

@@ -298,6 +298,7 @@ public class JPopupMenu extends JComponent implements Accessible,MenuElement {
      * it to the end of this menu.
      *
      * @param s the string for the menu item to be added
+     * @return a new {@code JMenuItem} created using {@code s}
      */
     public JMenuItem add(String s) {
         return add(new JMenuItem(s));
@@ -452,6 +453,9 @@ public class JPopupMenu extends JComponent implements Accessible,MenuElement {
     /**
      * Returns a properly configured <code>PropertyChangeListener</code>
      * which updates the control as changes to the <code>Action</code> occur.
+     *
+     * @param b the menu item for which to create a listener
+     * @return a properly configured {@code PropertyChangeListener}
      */
     protected PropertyChangeListener createActionChangeListener(JMenuItem b) {
         return b.createActionPropertyChangeListener0(b.getAction());
@@ -1530,6 +1534,9 @@ public class JPopupMenu extends JComponent implements Accessible,MenuElement {
     @SuppressWarnings("serial")
     static public class Separator extends JSeparator
     {
+        /**
+         * Constructs a popup menu-specific Separator.
+         */
         public Separator( )
         {
             super( JSeparator.HORIZONTAL );
@@ -1553,6 +1560,7 @@ public class JPopupMenu extends JComponent implements Accessible,MenuElement {
      * Returns true if the <code>MouseEvent</code> is considered a popup trigger
      * by the <code>JPopupMenu</code>'s currently installed UI.
      *
+     * @param e a {@code MouseEvent}
      * @return true if the mouse event is a popup trigger
      * @since 1.3
      */

jdk/src/share/classes/javax/swing/JScrollPane.java

@@ -1102,6 +1102,7 @@ public class JScrollPane extends JComponent implements ScrollPaneConstants, Acce
      * <code>setColumnHeaderView</code>
      * to add a column header component and its viewport to the scroll pane.
      *
+     * @param columnHeader  a {@code JViewport} which is the new column header
      * @see #getColumnHeader
      * @see #setColumnHeaderView
      *
@@ -1299,6 +1300,7 @@ public class JScrollPane extends JComponent implements ScrollPaneConstants, Acce
      * Indicates whether or not scrolling will take place in response to the
      * mouse wheel.  Wheel scrolling is enabled by default.
      *
+     * @return true if mouse wheel scrolling is enabled, false otherwise
      * @see #setWheelScrollingEnabled
      * @since 1.4
      * @beaninfo
@@ -1448,9 +1450,12 @@ public class JScrollPane extends JComponent implements ScrollPaneConstants, Acce
     protected class AccessibleJScrollPane extends AccessibleJComponent
         implements ChangeListener, PropertyChangeListener {
 
+        /**
+         * this {@code JScrollPane}'s current {@code JViewport}
+         */
         protected JViewport viewPort = null;
 
-        /*
+        /**
          * Resets the viewport ChangeListener and PropertyChangeListener
          */
         public void resetViewPort() {

jdk/src/share/classes/javax/swing/JSpinner.java

@@ -149,6 +149,7 @@ public class JSpinner extends JComponent implements Accessible
      * a set of previous/next buttons, and an editor appropriate
      * for the model.
      *
+     * @param model  a model for the new spinner
      * @throws NullPointerException if the model is {@code null}
      */
     public JSpinner(SpinnerModel model) {
@@ -328,6 +329,7 @@ public class JSpinner extends JComponent implements Accessible
      * getModel().getValue()
      * </pre>
      *
+     * @return the current value of the model
      * @see #setValue
      * @see SpinnerModel#getValue
      */
@@ -349,6 +351,7 @@ public class JSpinner extends JComponent implements Accessible
      * getModel().setValue(value)
      * </pre>
      *
+     * @param value  new value for the spinner
      * @throws IllegalArgumentException if <code>value</code> isn't allowed
      * @see #getValue
      * @see SpinnerModel#setValue

jdk/src/share/classes/javax/swing/JTextField.java

@@ -675,6 +675,9 @@ public class JTextField extends JTextComponent implements SwingConstants {
      * that of the <code>Action</code>.
      *
      * @param a the textfield's action
+     * @return a {@code PropertyChangeListener} that is responsible for
+     *         listening for changes from the specified {@code Action} and
+     *         updating the appropriate properties
      * @since 1.3
      * @see Action
      * @see #setAction

jdk/src/share/classes/javax/swing/JWindow.java

@@ -272,6 +272,8 @@ public class JWindow extends Window implements Accessible,
     /**
      * Called by the constructor methods to create the default
      * <code>rootPane</code>.
+     *
+     * @return a new {@code JRootPane}
      */
     protected JRootPane createRootPane() {
         JRootPane rp = new JRootPane();

jdk/src/share/classes/javax/swing/ProgressMonitor.java

@@ -369,6 +369,8 @@ public class ProgressMonitor implements Accessible
 
     /**
      * Returns true if the user hits the Cancel button in the progress dialog.
+     *
+     * @return true if the user hits the Cancel button in the progress dialog
      */
     public boolean isCanceled() {
         if (pane == null) return false;
@@ -396,6 +398,8 @@ public class ProgressMonitor implements Accessible
      * Returns the amount of time this object waits before deciding whether
      * or not to popup a progress monitor.
      *
+     * @return the amount of time in milliseconds this object waits before
+     *         deciding whether or not to popup a progress monitor
      * @see #setMillisToDecideToPopup
      */
     public int getMillisToDecideToPopup() {
@@ -419,6 +423,8 @@ public class ProgressMonitor implements Accessible
     /**
      * Returns the amount of time it will take for the popup to appear.
      *
+     * @return the amont of time in milliseconds it will take for the
+     *         popup to appear
      * @see #setMillisToPopup
      */
     public int getMillisToPopup() {

jdk/src/share/classes/javax/swing/SpinnerModel.java

@@ -88,6 +88,7 @@ public interface SpinnerModel
      * that case, <code>model.setValue(new Number(11))</code>
      * would throw an exception.
      *
+     * @param value  new value for the spinner
      * @throws IllegalArgumentException if <code>value</code> isn't allowed
      * @see #getValue
      */

jdk/src/share/classes/javax/swing/Timer.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
@@ -154,6 +154,9 @@ public class Timer implements Serializable
      * NOTE: all fields need to be handled in readResolve
      */
 
+    /**
+     * The collection of registered listeners
+     */
     protected EventListenerList listenerList = new EventListenerList();
 
     // The following field strives to maintain the following:
@@ -335,6 +338,7 @@ public class Timer implements 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>
@@ -410,6 +414,7 @@ public class Timer implements Serializable
      * Returns the delay, in milliseconds,
      * between firings of action events.
      *
+     * @return the delay, in milliseconds, between firings of action events
      * @see #setDelay
      * @see #getInitialDelay
      */
@@ -441,8 +446,9 @@ public class Timer implements Serializable
 
 
     /**
-     * Returns the <code>Timer</code>'s initial delay.
+     * Returns the {@code Timer}'s initial delay.
      *
+     * @return the {@code Timer}'s intial delay, in milliseconds
      * @see #setInitialDelay
      * @see #setDelay
      */
@@ -470,6 +476,8 @@ public class Timer implements Serializable
      * an action event
      * to its listeners multiple times.
      *
+     * @return true if the {@code Timer} will send an action event to its
+     *              listeners multiple times
      * @see #setRepeats
      */
     public boolean isRepeats() {
@@ -506,9 +514,11 @@ public class Timer implements Serializable
 
 
     /**
-     * Returns <code>true</code> if the <code>Timer</code> coalesces
+     * Returns {@code true} if the {@code Timer} coalesces
      * multiple pending action events.
      *
+     * @return true if the {@code Timer} coalesces multiple pending
+     *              action events
      * @see #setCoalesce
      */
     public boolean isCoalesce() {
@@ -555,8 +565,9 @@ public class Timer implements Serializable
 
 
     /**
-     * Returns <code>true</code> if the <code>Timer</code> is running.
+     * Returns {@code true} if the {@code Timer} is running.
      *
+     * @return true if the {@code Timer} is running, false otherwise
      * @see #start
      */
     public boolean isRunning() {