8251203: Fix "no comment" warnings in java.base/java.lang and java/io

Reviewed-by: dfuchs, lancea, mchung, naoto

src/java.base/share/classes/java/io/File.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 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
@@ -2231,6 +2231,9 @@ public class File
      * in case the path is reconstituted on a different host type.
      *
      * @serialData  Default fields followed by separator character.
+     *
+     * @param  s the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private synchronized void writeObject(java.io.ObjectOutputStream s)
@@ -2245,6 +2248,10 @@ public class File
      * The original separator character is read.  If it is different
      * than the separator character on this system, then the old separator
      * is replaced by the local separator.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private synchronized void readObject(java.io.ObjectInputStream s)

src/java.base/share/classes/java/io/FilePermission.java

@@ -1247,9 +1247,12 @@ final class FilePermissionCollection extends PermissionCollection
     /**
      * @serialData "permissions" field (a Vector containing the FilePermissions).
      */
-    /*
+    /**
      * Writes the contents of the perms field out as a Vector for
      * serialization compatibility with earlier releases.
+     *
+     * @param  out the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream out) throws IOException {
@@ -1263,8 +1266,12 @@ final class FilePermissionCollection extends PermissionCollection
         out.writeFields();
     }
 
-    /*
+    /**
      * Reads in a Vector of FilePermissions and saves them in the perms field.
+     *
+     * @param  in the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream in)

src/java.base/share/classes/java/io/ObjectStreamClass.java

@@ -93,6 +93,9 @@ public class ObjectStreamClass implements Serializable {
 
     @java.io.Serial
     private static final long serialVersionUID = -6120832682080437368L;
+    /**
+     * {@code ObjectStreamClass} has no fields for default serialization.
+     */
     @java.io.Serial
     private static final ObjectStreamField[] serialPersistentFields =
         NO_FIELDS;
@@ -2538,7 +2541,9 @@ public class ObjectStreamClass implements Serializable {
         }
     }
 
-    // a LRA cache of record deserialization constructors
+    /**
+     * A LRA cache of record deserialization constructors.
+     */
     @SuppressWarnings("serial")
     private static final class DeserializationConstructorsCache
         extends ConcurrentHashMap<DeserializationConstructorsCache.Key, MethodHandle>  {

src/java.base/share/classes/java/io/UncheckedIOException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 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
@@ -76,6 +76,9 @@ public class UncheckedIOException extends RuntimeException {
     /**
      * Called to read the object from a stream.
      *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      * @throws  InvalidObjectException
      *          if the object is invalid or has a cause that is not
      *          an {@code IOException}

src/java.base/share/classes/java/lang/AbstractStringBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -585,7 +585,12 @@ abstract class AbstractStringBuilder implements Appendable, CharSequence {
         return this;
     }
 
-    // Documentation in subclasses because of synchro difference
+    /**
+     * Appends the specified {@code StringBuffer} to this sequence.
+     *
+     * @param   sb   the {@code StringBuffer} to append.
+     * @return  a reference to this object.
+     */
     public AbstractStringBuilder append(StringBuffer sb) {
         return this.append((AbstractStringBuilder)sb);
     }

src/java.base/share/classes/java/lang/ClassNotFoundException.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
@@ -110,14 +110,14 @@ public class ClassNotFoundException extends ReflectiveOperationException {
     /**
      * Serializable fields for ClassNotFoundException.
      *
-     * @serialField ex Throwable
+     * @serialField ex Throwable  the {@code Throwable}
      */
     @java.io.Serial
     private static final ObjectStreamField[] serialPersistentFields = {
         new ObjectStreamField("ex", Throwable.class)
     };
 
-    /*
+    /**
      * Reconstitutes the ClassNotFoundException instance from a stream
      * and initialize the cause properly when deserializing from an older
      * version.
@@ -125,6 +125,10 @@ public class ClassNotFoundException extends ReflectiveOperationException {
      * The getException and getCause method returns the private "ex" field
      * in the older implementation and ClassNotFoundException::cause
      * was set to null.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException {
@@ -135,9 +139,12 @@ public class ClassNotFoundException extends ReflectiveOperationException {
         }
     }
 
-    /*
+    /**
      * To maintain compatibility with older implementation, write a serial
      * "ex" field with the cause as the value.
+     *
+     * @param  out the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream out) throws IOException {

src/java.base/share/classes/java/lang/ExceptionInInitializerError.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2019, 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
@@ -108,14 +108,14 @@ public class ExceptionInInitializerError extends LinkageError {
     /**
      * Serializable fields for ExceptionInInitializerError.
      *
-     * @serialField exception Throwable
+     * @serialField exception Throwable the exception
      */
     @java.io.Serial
     private static final ObjectStreamField[] serialPersistentFields = {
         new ObjectStreamField("exception", Throwable.class)
     };
 
-    /*
+    /**
      * Reconstitutes the ExceptionInInitializerError instance from a stream
      * and initialize the cause properly when deserializing from an older
      * version.
@@ -123,6 +123,10 @@ public class ExceptionInInitializerError extends LinkageError {
      * The getException and getCause method returns the private "exception"
      * field in the older implementation and ExceptionInInitializerError::cause
      * was set to null.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException {
@@ -133,9 +137,12 @@ public class ExceptionInInitializerError extends LinkageError {
         }
     }
 
-    /*
+    /**
      * To maintain compatibility with older implementation, write a serial
      * "exception" field with the cause as the value.
+     *
+     * @param  out the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream out) throws IOException {

src/java.base/share/classes/java/lang/StackTraceElement.java

@@ -60,13 +60,37 @@ public final class StackTraceElement implements java.io.Serializable {
     private transient Class<?> declaringClassObject;
 
     // Normally initialized by VM
+    /**
+     * The name of the class loader.
+     */
     private String classLoaderName;
+    /**
+     * The module name.
+     */
     private String moduleName;
+    /**
+     * The module version.
+     */
     private String moduleVersion;
+    /**
+     * The declaring class.
+     */
     private String declaringClass;
+    /**
+     * The method name.
+     */
     private String methodName;
+    /**
+     * The source file name.
+     */
     private String fileName;
+    /**
+     * The source line number.
+     */
     private int    lineNumber;
+    /**
+     * Control to show full or partial module, package, and class names.
+     */
     private byte   format = 0; // Default to show all
 
     /**

src/java.base/share/classes/java/lang/String.java

@@ -1236,6 +1236,10 @@ public final class String
      */
     public static final Comparator<String> CASE_INSENSITIVE_ORDER
                                          = new CaseInsensitiveComparator();
+
+    /**
+     * CaseInsensitiveComparator for Strings.
+     */
     private static class CaseInsensitiveComparator
             implements Comparator<String>, java.io.Serializable {
         // use serialVersionUID from JDK 1.2.2 for interoperability

src/java.base/share/classes/java/lang/StringBuffer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 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,6 +25,7 @@
 
 package java.lang;
 
+import java.io.IOException;
 import java.util.Arrays;
 import jdk.internal.HotSpotIntrinsicCandidate;
 
@@ -733,8 +734,11 @@ import jdk.internal.HotSpotIntrinsicCandidate;
     };
 
     /**
-     * readObject is called to restore the state of the StringBuffer from
+     * The {@code writeObject} method is called to write the state of the {@code StringBuffer} to
      * a stream.
+     *
+     * @param  s the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private synchronized void writeObject(java.io.ObjectOutputStream s)
@@ -753,8 +757,12 @@ import jdk.internal.HotSpotIntrinsicCandidate;
     }
 
     /**
-     * readObject is called to restore the state of the StringBuffer from
+     * The {@code readObject} method is called to restore the state of the {@code StringBuffer} from
      * a stream.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)

src/java.base/share/classes/java/lang/StringBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -27,6 +27,8 @@ package java.lang;
 
 import jdk.internal.HotSpotIntrinsicCandidate;
 
+import java.io.IOException;
+
 /**
  * A mutable sequence of characters.  This class provides an API compatible
  * with {@code StringBuffer}, but with no guarantee of synchronization.
@@ -458,6 +460,9 @@ public final class StringBuilder
      *             {@code char} array may be greater than the number of
      *             characters currently stored in the string builder, in which
      *             case extra characters are ignored.
+     *
+     * @param  s the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream s)
@@ -476,10 +481,14 @@ public final class StringBuilder
     /**
      * readObject is called to restore the state of the StringBuffer from
      * a stream.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)
-        throws java.io.IOException, ClassNotFoundException {
+        throws IOException, ClassNotFoundException {
         s.defaultReadObject();
         count = s.readInt();
         char[] val = (char[]) s.readObject();

src/java.base/share/classes/java/lang/Throwable.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 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
@@ -902,6 +902,10 @@ public class Throwable implements Serializable {
      * Note that there are no constraints on the value the {@code
      * cause} field can hold; both {@code null} and {@code this} are
      * valid values for the field.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream s)
@@ -991,6 +995,9 @@ public class Throwable implements Serializable {
      * A {@code null} stack trace field is represented in the serial
      * form as a one-element array whose element is equal to {@code
      * new StackTraceElement("", "", null, Integer.MIN_VALUE)}.
+     *
+     * @param  s the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private synchronized void writeObject(ObjectOutputStream s)

src/java.base/share/classes/java/lang/TypeNotPresentException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -47,6 +47,9 @@ public class TypeNotPresentException extends RuntimeException {
     @java.io.Serial
     private static final long serialVersionUID = -5101214195716534496L;
 
+    /**
+     * The type name.
+     */
     private String typeName;
 
     /**

src/java.base/share/classes/java/lang/annotation/IncompleteAnnotationException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -42,7 +42,13 @@ public class IncompleteAnnotationException extends RuntimeException {
     @java.io.Serial
     private static final long serialVersionUID = 8445097402741811912L;
 
+    /**
+     * The annotation type.
+     */
     private Class<? extends Annotation> annotationType;
+    /**
+     * The element name.
+     */
     private String elementName;
 
     /**

src/java.base/share/classes/java/lang/invoke/InvokerBytecodeGenerator.java

@@ -937,6 +937,9 @@ class InvokerBytecodeGenerator {
         }
     }
 
+    /**
+     * The BytecodeGenerationException.
+     */
     @SuppressWarnings("serial")
     static final class BytecodeGenerationException extends RuntimeException {
         BytecodeGenerationException(Exception cause) {

src/java.base/share/classes/java/lang/invoke/SerializedLambda.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 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
@@ -67,15 +67,45 @@ import java.util.Objects;
 public final class SerializedLambda implements Serializable {
     @java.io.Serial
     private static final long serialVersionUID = 8025925345765570181L;
+    /**
+     * The capturing class.
+     */
     private final Class<?> capturingClass;
+    /**
+     * The functional interface class.
+     */
     private final String functionalInterfaceClass;
+    /**
+     * The functional interface method name.
+     */
     private final String functionalInterfaceMethodName;
+    /**
+     * The functional interface method signature.
+     */
     private final String functionalInterfaceMethodSignature;
+    /**
+     * The implementation class.
+     */
     private final String implClass;
+    /**
+     * The implementation method name.
+     */
     private final String implMethodName;
+    /**
+     * The implementation method signature.
+     */
     private final String implMethodSignature;
+    /**
+     * The implementation method kind.
+     */
     private final int implMethodKind;
+    /**
+     * The instantiated method type.
+     */
     private final String instantiatedMethodType;
+    /**
+     * The captured arguments.
+     */
     @SuppressWarnings("serial") // Not statically typed as Serializable
     private final Object[] capturedArgs;
 
@@ -227,6 +257,11 @@ public final class SerializedLambda implements Serializable {
         return capturedArgs[i];
     }
 
+    /**
+     * Resolve a {@code SerializedLambda} to an object.
+     * @return a SerializedLambda
+     * @throws ObjectStreamException if the object is not valid
+     */
     @java.io.Serial
     private Object readResolve() throws ObjectStreamException {
         try {

src/java.base/share/classes/java/lang/reflect/UndeclaredThrowableException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 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
@@ -107,17 +107,21 @@ public class UndeclaredThrowableException extends RuntimeException {
     /**
      * Serializable fields for UndeclaredThrowableException.
      *
-     * @serialField undeclaredThrowable Throwable
+     * @serialField undeclaredThrowable Throwable the undeclared exception
      */
     @java.io.Serial
     private static final ObjectStreamField[] serialPersistentFields = {
         new ObjectStreamField("undeclaredThrowable", Throwable.class)
     };
 
-    /*
+    /**
      * Reconstitutes the UndeclaredThrowableException instance from a stream
      * and initialize the cause properly when deserializing from an older
      * version.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException {
@@ -128,9 +132,12 @@ public class UndeclaredThrowableException extends RuntimeException {
         }
     }
 
-    /*
+    /**
      * To maintain compatibility with older implementation, write a serial
      * "ex" field with the cause as the value.
+     *
+     * @param  out the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream out) throws IOException {

src/java.base/share/classes/java/time/temporal/ValueRange.java

@@ -354,6 +354,7 @@ public final class ValueRange implements Serializable {
      * Check that the values are valid.
      *
      * @param s the stream to read
+     * @throws IOException if an I/O error occurs
      * @throws InvalidObjectException if
      *     the smallest minimum is greater than the smallest maximum,
      *  or the smallest maximum is greater than the largest maximum

src/java.base/share/classes/java/time/temporal/WeekFields.java

@@ -359,6 +359,7 @@ public final class WeekFields implements Serializable {
      * Check that the values are valid.
      *
      * @param s the stream to read
+     * @throws IOException if an I/O error occurs
      * @throws InvalidObjectException if the serialized object has an invalid
      *     value for firstDayOfWeek or minimalDays.
      * @throws ClassNotFoundException if a class cannot be resolved