8251123: doclint warnings about missing javadoc tags and comments

Reviewed-by: jdv, prr
openjdk · Oct 6, 2020 · f397b60 · f397b60 · bridgekeeper · Oct 6, 2020
1 parent c9d1dcc
commit f397b60
Show file tree

Hide file tree

Showing 69 changed files with 1,091 additions and 447 deletions.
diff --git a/src/java.desktop/share/classes/java/applet/Applet.java b/src/java.desktop/share/classes/java/applet/Applet.java
@@ -99,7 +99,10 @@ public Applet() throws HeadlessException {
     /**
      * Read an applet from an object input stream.
      *
-     * @param  s an object input stream
+     * @param  s the {@code ObjectInputStream} to read
+     * @throws ClassNotFoundException if the class of a serialized object could
+     *         not be found
+     * @throws IOException if an I/O error occurs
      * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
      *         returns {@code true}
      * @serial

diff --git a/src/java.desktop/share/classes/java/awt/AWTEvent.java b/src/java.desktop/share/classes/java/awt/AWTEvent.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2020, 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
@@ -87,6 +87,9 @@
  */
 public abstract class AWTEvent extends EventObject {
 
+    /**
+     * The private data.
+     */
     private byte[] bdata;
 
     /**

diff --git a/src/java.desktop/share/classes/java/awt/AWTKeyStroke.java b/src/java.desktop/share/classes/java/awt/AWTKeyStroke.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2020, 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
@@ -22,18 +22,20 @@
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
+
 package java.awt;
 
-import java.awt.event.KeyEvent;
-import sun.awt.AppContext;
 import java.awt.event.InputEvent;
+import java.awt.event.KeyEvent;
+import java.io.Serializable;
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.StringTokenizer;
-import java.io.Serializable;
-import java.lang.reflect.Modifier;
-import java.lang.reflect.Field;
+
+import sun.awt.AppContext;
 import sun.swing.SwingAccessor;
 
 /**
@@ -77,9 +79,25 @@ public class AWTKeyStroke implements Serializable {
     //A key withing the cache
     private static AWTKeyStroke APP_CONTEXT_KEYSTROKE_KEY = new AWTKeyStroke();
 
+    /**
+     * The character value for a keyboard key.
+     */
     private char keyChar = KeyEvent.CHAR_UNDEFINED;
+
+    /**
+     * The key code for this {@code AWTKeyStroke}.
+     */
     private int keyCode = KeyEvent.VK_UNDEFINED;
+
+    /**
+     * The bitwise-ored combination of any modifiers.
+     */
     private int modifiers;
+
+    /**
+     * {@code true} if this {@code AWTKeyStroke} corresponds to a key release;
+     * {@code false} otherwise.
+     */
     private boolean onKeyRelease;
 
     static {

diff --git a/src/java.desktop/share/classes/java/awt/Button.java b/src/java.desktop/share/classes/java/awt/Button.java
@@ -25,14 +25,20 @@
 
 package java.awt;
 
+import java.awt.event.ActionEvent;
+import java.awt.event.ActionListener;
 import java.awt.peer.ButtonPeer;
 import java.beans.BeanProperty;
-import java.util.EventListener;
-import java.awt.event.*;
-import java.io.ObjectOutputStream;
-import java.io.ObjectInputStream;
 import java.io.IOException;
-import javax.accessibility.*;
+import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
+import java.util.EventListener;
+
+import javax.accessibility.Accessible;
+import javax.accessibility.AccessibleAction;
+import javax.accessibility.AccessibleContext;
+import javax.accessibility.AccessibleRole;
+import javax.accessibility.AccessibleValue;
 
 /**
  * This class creates a labeled button. The application can cause
@@ -428,9 +434,8 @@ protected String paramString() {
 
     /* Serialization support.
      */
-
-    /*
-     * Button Serial Data Version.
+    /**
+     * Serialized data version.
      * @serial
      */
     private int buttonSerializedDataVersion = 1;
@@ -449,7 +454,8 @@ protected String paramString() {
      *   {@code actionListenerK} indicating an
      *     {@code ActionListener} object
      *
-     * @param s the {@code ObjectOutputStream} to write
+     * @param  s the {@code ObjectOutputStream} to write
+     * @throws IOException if an I/O error occurs
      * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
      * @see java.awt.Component#actionListenerK
      * @see #readObject(ObjectInputStream)
@@ -469,10 +475,12 @@ private void writeObject(ObjectOutputStream s)
      * receive action events fired by the button.
      * Unrecognized keys or values will be ignored.
      *
-     * @param s the {@code ObjectInputStream} to read
-     * @exception HeadlessException if
-     *   {@code GraphicsEnvironment.isHeadless} returns
-     *   {@code true}
+     * @param  s the {@code ObjectInputStream} to read
+     * @throws ClassNotFoundException if the class of a serialized object could
+     *         not be found
+     * @throws IOException if an I/O error occurs
+     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+     *         returns {@code true}
      * @serial
      * @see #removeActionListener(ActionListener)
      * @see #addActionListener(ActionListener)

diff --git a/src/java.desktop/share/classes/java/awt/CardLayout.java b/src/java.desktop/share/classes/java/awt/CardLayout.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2020, 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
@@ -25,15 +25,14 @@
 
 package java.awt;
 
-import java.util.Hashtable;
-import java.util.Vector;
-import java.util.Enumeration;
-
-import java.io.Serializable;
+import java.io.IOException;
 import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
 import java.io.ObjectStreamField;
-import java.io.IOException;
+import java.io.Serializable;
+import java.util.Enumeration;
+import java.util.Hashtable;
+import java.util.Vector;
 
 /**
  * A {@code CardLayout} object is a layout manager for a
@@ -68,8 +67,8 @@ public class CardLayout implements LayoutManager2,
      */
     Vector<Card> vector = new Vector<>();
 
-    /*
-     * A pair of Component and String that represents its name.
+    /**
+     * A pair of component and string that represents its name.
      */
     class Card implements Serializable {
         static final long serialVersionUID = 6640330810709497518L;
@@ -110,10 +109,10 @@ public Card(String cardName, Component cardComponent) {
     /**
      * @serialField tab         Hashtable
      *      deprecated, for forward compatibility only
-     * @serialField hgap        int
-     * @serialField vgap        int
-     * @serialField vector      Vector
-     * @serialField currentCard int
+     * @serialField hgap        int the horizontal Layout gap
+     * @serialField vgap        int the vertical Layout gap
+     * @serialField vector      Vector the pairs of components and their names
+     * @serialField currentCard int the index of Component currently displayed
      */
     private static final ObjectStreamField[] serialPersistentFields = {
         new ObjectStreamField("tab", Hashtable.class),
@@ -559,6 +558,11 @@ public String toString() {
 
     /**
      * Reads serializable fields from stream.
+     *
+     * @param  s the {@code ObjectInputStream} to read
+     * @throws ClassNotFoundException if the class of a serialized object could
+     *         not be found
+     * @throws IOException if an I/O error occurs
      */
     @SuppressWarnings("unchecked")
     private void readObject(ObjectInputStream s)
@@ -591,6 +595,9 @@ private void readObject(ObjectInputStream s)
 
     /**
      * Writes serializable fields to stream.
+     *
+     * @param  s the {@code ObjectOutputStream} to write
+     * @throws IOException if an I/O error occurs
      */
     private void writeObject(ObjectOutputStream s)
         throws IOException

diff --git a/src/java.desktop/share/classes/java/awt/Checkbox.java b/src/java.desktop/share/classes/java/awt/Checkbox.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2020, 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
@@ -22,16 +22,24 @@
  * or visit www.oracle.com if you need additional information or have any
  * questions.
  */
+
 package java.awt;
 
+import java.awt.event.ItemEvent;
+import java.awt.event.ItemListener;
 import java.awt.peer.CheckboxPeer;
-import java.awt.event.*;
-import java.util.EventListener;
-import java.io.ObjectOutputStream;
-import java.io.ObjectInputStream;
 import java.io.IOException;
-import javax.accessibility.*;
+import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
+import java.util.EventListener;
 
+import javax.accessibility.Accessible;
+import javax.accessibility.AccessibleAction;
+import javax.accessibility.AccessibleContext;
+import javax.accessibility.AccessibleRole;
+import javax.accessibility.AccessibleState;
+import javax.accessibility.AccessibleStateSet;
+import javax.accessibility.AccessibleValue;
 
 /**
  * A check box is a graphical component that can be in either an
@@ -602,8 +610,8 @@ protected String paramString() {
     /* Serialization support.
      */
 
-    /*
-     * Serialized data version
+    /**
+     * Serialized data version.
      * @serial
      */
     private int checkboxSerializedDataVersion = 1;
@@ -615,7 +623,8 @@ protected String paramString() {
      * {@code ItemListeners} are detected and
      * no attempt is made to serialize them.
      *
-     * @param s the {@code ObjectOutputStream} to write
+     * @param  s the {@code ObjectOutputStream} to write
+     * @throws IOException if an I/O error occurs
      * @serialData {@code null} terminated sequence of 0
      *   or more pairs; the pair consists of a {@code String}
      *   and an {@code Object}; the {@code String} indicates
@@ -642,10 +651,12 @@ private void writeObject(ObjectOutputStream s)
      * item events fired by the {@code Checkbox}.
      * Unrecognized keys or values will be ignored.
      *
-     * @param s the {@code ObjectInputStream} to read
-     * @exception HeadlessException if
-     *   {@code GraphicsEnvironment.isHeadless} returns
-     *   {@code true}
+     * @param  s the {@code ObjectInputStream} to read
+     * @throws ClassNotFoundException if the class of a serialized object could
+     *         not be found
+     * @throws IOException if an I/O error occurs
+     * @throws HeadlessException if {@code GraphicsEnvironment.isHeadless()}
+     *         returns {@code true}
      * @serial
      * @see #removeItemListener(ItemListener)
      * @see #addItemListener(ItemListener)

diff --git a/src/java.desktop/share/classes/java/awt/CheckboxMenuItem.java b/src/java.desktop/share/classes/java/awt/CheckboxMenuItem.java
@@ -25,6 +25,7 @@
 
 package java.awt;
 
+import java.awt.event.ActionListener;
 import java.awt.event.ItemEvent;
 import java.awt.event.ItemListener;
 import java.awt.peer.CheckboxMenuItemPeer;
@@ -426,8 +427,8 @@ public String paramString() {
     /* Serialization support.
      */
 
-    /*
-     * Serial Data Version
+    /**
+     * Serialized data version.
      * @serial
      */
     private int checkboxMenuItemSerializedDataVersion = 1;
@@ -439,7 +440,8 @@ public String paramString() {
      * {@code ItemListeners} are detected and
      * no attempt is made to serialize them.
      *
-     * @param s the {@code ObjectOutputStream} to write
+     * @param  s the {@code ObjectOutputStream} to write
+     * @throws IOException if an I/O error occurs
      * @serialData {@code null} terminated sequence of
      *  0 or more pairs; the pair consists of a {@code String}
      *  and an {@code Object}; the {@code String} indicates
@@ -460,17 +462,20 @@ private void writeObject(ObjectOutputStream s)
       s.writeObject(null);
     }
 
-    /*
+    /**
      * Reads the {@code ObjectInputStream} and if it
      * isn't {@code null} adds a listener to receive
      * item events fired by the {@code Checkbox} menu item.
      * Unrecognized keys or values will be ignored.
      *
-     * @param s the {@code ObjectInputStream} to read
+     * @param  s the {@code ObjectInputStream} to read
+     * @throws ClassNotFoundException if the class of a serialized object could
+     *         not be found
+     * @throws IOException if an I/O error occurs
      * @serial
-     * @see removeActionListener()
-     * @see addActionListener()
-     * @see #writeObject
+     * @see #removeActionListener(ActionListener)
+     * @see #addActionListener(ActionListener)
+     * @see #writeObject(ObjectOutputStream)
      */
     private void readObject(ObjectInputStream s)
       throws ClassNotFoundException, IOException