Summary

The changes done under JDK-8278175 suppress on a per-file basis various missing comments that would otherwise trigger doclint warnings. JDK-8278254 unsuppress this warnings by adding the missing comments.

Problem

Various missing comments were causing doclint warnings in various classes in java.desktop module.

Solution

Comments were added to various classes, methods so that we can remove the suppression of doclint warnings

Specification

src/java.desktop/share/classes/java/awt/BufferCapabilities.java

     /**
+     * Returns the image capabilities of the front (displayed) buffer.
+     *
      * @return the image capabilities of the front (displayed) buffer
      */
     public ImageCapabilities getFrontBufferCapabilities() {
         return frontCaps;

     /**
+     * Returns the image capabilities of all back buffers (intermediate buffers
+     * are considered back buffers).
+     *
      * @return the image capabilities of all back buffers (intermediate buffers
      * are considered back buffers)
      */
     public ImageCapabilities getBackBufferCapabilities() {



     /**
-     * @return whether or not the buffer strategy uses page flipping; a set of
-     * buffers that uses page flipping
+     * Returns whether or not the buffer strategy uses page flipping.
+     * A set of buffers that uses page flipping
      * can swap the contents internally between the front buffer and one or
      * more back buffers by switching the video pointer (or by copying memory
      * internally).  A non-flipping set of
      * buffers uses blitting to copy the contents from one buffer to
      * another; when this is the case, {@code getFlipContents} returns
-     * {@code null}
+     * {@code null}.
+     *
+     * @return whether or not the buffer strategy uses page flipping
      */
     public boolean isPageFlipping() {



     /**
-     * @return the resulting contents of the back buffer after page-flipping.
+     * Returns the resulting contents of the back buffer after page-flipping.
      * This value is {@code null} when the {@code isPageFlipping}
      * This value is {@code null} when the {@code isPageFlipping}
      * returns {@code false}, implying blitting.  It can be one of
      * {@code FlipContents.UNDEFINED}
      * (the assumed default), {@code FlipContents.BACKGROUND},
      * {@code FlipContents.PRIOR}, or
      * {@code FlipContents.COPIED}.
+     *
+     * @return the resulting contents of the back buffer after page-flipping
      public FlipContents getFlipContents() {

     /**
-     * @return whether page flipping is only available in full-screen mode.  If this
+     * Returns whether page flipping is only available in full-screen mode.  If this
      * is {@code true}, full-screen exclusive mode is required for
      * page-flipping.
+     *
+     * @return whether page flipping is only available in full-screen mode
      * @see #isPageFlipping
      * @see GraphicsDevice#setFullScreenWindow
      */
     public boolean isFullScreenRequired() {

     /**
-     * @return whether or not
+     * Returns whether or not
      * page flipping can be performed using more than two buffers (one or more
      * intermediate buffers as well as the front and back buffer).
+     *
+     * @return whether or not
+     * page flipping can be performed using more than two buffers
      * @see #isPageFlipping
      */
     public boolean isMultiBufferAvailable() {

src/java.desktop/share/classes/java/awt/Component.java

     /**
-     * @return direct access to the back buffer, as an image.
+     * Provides direct access to the back buffer as an image.
+     *
+     * @return the back buffer as an image
      * @exception IllegalStateException if the buffers have not yet
      * been created
      */
     protected Image getBackBuffer() {

     /**
+     * Returns whether or not paint messages received from the operating system
+     * should be ignored.
+     *
      * @return whether or not paint messages received from the operating system
      * should be ignored
      *
     public boolean getIgnoreRepaint() {

src/java.desktop/share/classes/javax/swing/DefaultListSelectionModel.java

     /**
+     * Notifies <code>ListSelectionListeners</code> that the value
+     * of the selection, in the closed interval <code>firstIndex</code>,
+     * <code>lastIndex</code>, has changed and if this is the final change
+     * in the series of adjustments.
+     *
      * @param firstIndex the first index in the interval
      * @param lastIndex the last index in the interval
      * @param isAdjusting true if this is the final change in a series of
      *          adjustments
      * @see EventListenerList

     protected void fireValueChanged(int firstIndex, int lastIndex, boolean isAdjusting)

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

     /**
+     * The <code>JRootPane</code> instance that manages the
+     * <code>contentPane</code>.
+     *
      * @see #getRootPane
      * @see #setRootPane
      */
     protected JRootPane rootPane;

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

     /**
+     * The <code>JRootPane</code> instance that manages the
+     * <code>contentPane</code>.
+     *
      * @see #getRootPane
      * @see #setRootPane
      */
     protected JRootPane rootPane;

src/java.desktop/share/classes/javax/swing/JScrollBar.java

     /**
+     * Orientation of this scrollBar.
+     *
      * @see #setOrientation
      */
     protected int orientation;

     /**
+     * Stores the amount by which the value of the scrollbar is changed
+     * upon a unit up/down request.
+     *
      * @see #setUnitIncrement
      */
     protected int unitIncrement;


     /**
+     * Stores the amount by which the value of the scrollbar is changed
+     * upon a block (usually "page") up/down request.
+     *
      * @see #setBlockIncrement
      */
     protected int blockIncrement;

src/java.desktop/share/classes/javax/swing/filechooser/FileSystemView.java

     /**
+     * Returns a <code>File</code> object which is normally constructed with <code>new
+     * File(parent, fileName)</code> except when the parent and child are both
+     * special folders, in which case the <code>File</code> is a wrapper containing
+     * a ShellFolder object.
      *
      * @param parent a <code>File</code> object representing a directory or special folder
      * @param fileName a name of a file or folder which exists in <code>parent</code>
-     * @return a File object. This is normally constructed with <code>new
-     * File(parent, fileName)</code> except when parent and child are both
-     * special folders, in which case the <code>File</code> is a wrapper containing
-     * a <code>ShellFolder</code> object.
+     * @return a File object.
      * @since 1.4
      */
     public File getChild(File parent, String fileName) {

src/java.desktop/share/classes/javax/swing/plaf/basic/BasicMenuItemUI.java

     /**
+     * Registers the subcomponents of the menu.
      *
      * @param menuItem a menu item
      * @since 1.3
      */
     protected void installComponents(JMenuItem menuItem){

src/java.desktop/share/classes/javax/swing/plaf/metal/MetalBorders.java

     /**
-     * The class represents the border of a {@code JTestField}.
+     * Border for a {@code JTextField}.
      */
     @SuppressWarnings("serial") // Superclass is not serializable across versions
     public static class TextFieldBorder extends Flush3DBorder {

     /**
+     * Border for a {@code JToggleButton}.
+     *
      * @since 1.3
      */
     @SuppressWarnings("serial") // Superclass is not serializable across versions
     public static class ToggleButtonBorder extends ButtonBorder {
     /**

src/java.desktop/share/classes/javax/swing/text/LayeredHighlighter.java

  /**
+  * Implementation of {@code Highlighter} interface to mark up the
+  * background of leaf views with colored areas.
   *
   * @author  Scott Violet
   * @author  Timothy Prinzing
   * @see     Highlighter
   */
- @SuppressWarnings("doclint:missing")
  public abstract class LayeredHighlighter implements Highlighter {

      /**
+      * Paints a portion of a highlight.
+      *
       * @return a shape
       * @param g Graphics used to draw
       * @param p0 starting offset of view
       * @param p1 ending offset of view
       * @param viewBounds Bounds of View
      public abstract Shape paintLayer(Graphics g, int p0, int p1,

src/java.desktop/share/classes/javax/swing/text/html/HTML.java

-        /** @since 1.3 */
+        /**
+         * Constructs a {@code Tag}.
+         *
+         * @since 1.3
+         */
         public Tag() {}

src/java.desktop/share/classes/javax/swing/text/html/HTMLEditorKit.java

         /**
+         * Returns <code>HTMLDocument</code> of the given <code>JEditorPane</code>.
+         *
          * @param e the JEditorPane
          * @return HTMLDocument of <code>e</code>.
          */
         protected HTMLDocument getHTMLDocument(JEditorPane e) {

         /**
+         * Returns <code>HTMLEditorKit</code> of the given <code>JEditorPane</code>.
+         *
          * @param e the JEditorPane
          * @return HTMLEditorKit for <code>e</code>.
          */
         protected HTMLEditorKit getHTMLEditorKit(JEditorPane e) {

src/java.desktop/share/classes/javax/swing/text/html/parser/AttributeList.java

     /**
+     * Returns the attribute name.
+     *
      * @return attribute name
      */
     public String getName() {


     /**
+     * Returns the attribute type.
+     *
      * @return attribute type
      * @see DTDConstants
      */
     public int getType() {


     /**
+     * Returns attribute modifier.
+     *
      * @return attribute modifier
      * @see DTDConstants
      */
     public int getModifier() {


     /**
+     * Returns possible attribute values.
+     *
      * @return possible attribute values
      */
     public Enumeration<?> getValues() {

     /**
+     * Returns default attribute value.
+     *
      * @return default attribute value
      */
     public String getValue() {


     /**
+     * Returns the next attribute in the list.
+     *
      * @return the next attribute in the list
      */
     public AttributeList getNext() {

src/java.desktop/share/classes/javax/swing/text/html/parser/Parser.java

     /**
+     * Returns the line number of the line currently being parsed.
+     *
      * @return the line number of the line currently being parsed
      */
     protected int getCurrentLine() {

src/java.desktop/share/classes/javax/swing/undo/UndoableEditSupport.java

     /**
-     *
+     * Starts a compound edit update.
      */
     public synchronized void beginUpdate() {

src/java.desktop/share/classes/java/beans/beancontext/BeanContextSupport.java

     /**
-     * Use serialVersionUID from JDK 1.7 for interoperability.
+     * A protected nested class containing per-child information
+     * in the {@code children} hashtable.
      */
+    protected class BCSChild implements Serializable {

src/java.desktop/share/classes/java/beans/beancontext/BeanContextServicesSupport.java

+    /**
+     * A protected nested class containing per-child information
+     * in the {@code children} hashtable.
+     */
     protected class BCSSChild extends BeanContextSupport.BCSChild  {

+    /**
+     * Subclasses may subclass this nested class to represent a proxy for
+     * each BeanContextServiceProvider.
+     */
     protected class BCSSProxyServiceProvider implements BeanContextServiceProvider, BeanContextServiceRevokedListener {

src/java.desktop/share/classes/java/awt/event/KeyEvent.java

     /* For European keyboards *
-    /** @since 1.2 */
+    /**
+     * Constant for the Dead Grave key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_GRAVE               = 0x80;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Acute key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_ACUTE               = 0x81;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Circumflex key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_CIRCUMFLEX          = 0x82;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Tilde key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_TILDE               = 0x83;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Macron key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_MACRON              = 0x84;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Breve key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_BREVE               = 0x85;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Above Dot key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_ABOVEDOT            = 0x86;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Diaeresis key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_DIAERESIS           = 0x87;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Above Ring key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_ABOVERING           = 0x88;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Double Acute key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_DOUBLEACUTE         = 0x89;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Caron key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_CARON               = 0x8a;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Cedilla key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_CEDILLA             = 0x8b;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Ogonek key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_OGONEK              = 0x8c;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Iota key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_IOTA                = 0x8d;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Voiced Sound key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_VOICED_SOUND        = 0x8e;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Dead Semivoiced Sound key.
+     * @since 1.2
+     */
     public static final int VK_DEAD_SEMIVOICED_SOUND    = 0x8f;

-    /** @since 1.2 */
+    /**
+     * Constant for the "&" key.
+     * @since 1.2
+     */
     public static final int VK_AMPERSAND                = 0x96;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the "*" key.
+     * @since 1.2
+     */
     public static final int VK_ASTERISK                 = 0x97;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the """" key.
+     * @since 1.2
+     */
     public static final int VK_QUOTEDBL                 = 0x98;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the "<" key.
+     * @since 1.2
+     */
     public static final int VK_LESS                     = 0x99;

-    /** @since 1.2 */
+    /**
+     * Constant for the ">" key.
+     * @since 1.2
+     */
     public static final int VK_GREATER                  = 0xa0;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the "{" key.
+     * @since 1.2
+     */
     public static final int VK_BRACELEFT                = 0xa1;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the "}" key.
+     * @since 1.2
+     */
     public static final int VK_BRACERIGHT               = 0xa2;


     /* for Sun keyboards */
-    /** @since 1.2 */
+    /**
+     * Constant for the Cut key.
+     * @since 1.2
+     */
     public static final int VK_CUT                      = 0xFFD1;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Copy key.
+     * @since 1.2
+     */
     public static final int VK_COPY                     = 0xFFCD;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Paste key.
+     * @since 1.2
+     */
     public static final int VK_PASTE                    = 0xFFCF;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Undo key.
+     * @since 1.2
+     */
     public static final int VK_UNDO                     = 0xFFCB;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Again key.
+     * @since 1.2
+     */
     public static final int VK_AGAIN                    = 0xFFC9;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Find key.
+     * @since 1.2
+     */
     public static final int VK_FIND                     = 0xFFD0;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Props key.
+     * @since 1.2
+     */
     public static final int VK_PROPS                    = 0xFFCA;
-    /** @since 1.2 */
+
+    /**
+     * Constant for the Stop key.
+     * @since 1.2
+     */
     public static final int VK_STOP                     = 0xFFC8;