8300867: Fix document issues in java.io

Reviewed-by: alanb, lancea, iris

Author: minborg

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

@@ -342,7 +342,7 @@ private int read1(byte[] b, int off, int len) throws IOException {
      *
      * </ul> If the first {@code read} on the underlying stream returns
      * {@code -1} to indicate end-of-file then this method returns
-     * {@code -1}.  Otherwise this method returns the number of bytes
+     * {@code -1}.  Otherwise, this method returns the number of bytes
      * actually read.
      *
      * <p> Subclasses of this class are encouraged, but not required, to

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2023, 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
@@ -39,7 +39,7 @@ class DeleteOnExitHook {
     static {
         // DeleteOnExitHook must be the last shutdown hook to be invoked.
         // Application shutdown hooks may add the first file to the
-        // delete on exit list and cause the DeleteOnExitHook to be
+        // delete-on-exit list and cause the DeleteOnExitHook to be
         // registered during shutdown in progress. So set the
         // registerShutdownInProgress parameter to true.
         SharedSecrets.getJavaLangAccess()

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2023, 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
@@ -759,7 +759,7 @@ public URI toURI() {
      * Tests whether the application can read the file denoted by this
      * abstract pathname. On some platforms it may be possible to start the
      * Java virtual machine with special privileges that allow it to read
-     * files that are marked as unreadable. Consequently this method may return
+     * files that are marked as unreadable. Consequently, this method may return
      * {@code true} even though the file does not have read permissions.
      *
      * @return  {@code true} if and only if the file specified by this
@@ -787,7 +787,7 @@ public boolean canRead() {
      * Tests whether the application can modify the file denoted by this
      * abstract pathname. On some platforms it may be possible to start the
      * Java virtual machine with special privileges that allow it to modify
-     * files that are marked read-only. Consequently this method may return
+     * files that are marked read-only. Consequently, this method may return
      * {@code true} even though the file is marked read-only.
      *
      * @return  {@code true} if and only if the file system actually
@@ -1779,7 +1779,7 @@ public boolean setExecutable(boolean executable) {
      * Tests whether the application can execute the file denoted by this
      * abstract pathname. On some platforms it may be possible to start the
      * Java virtual machine with special privileges that allow it to execute
-     * files that are not marked executable. Consequently this method may return
+     * files that are not marked executable. Consequently, this method may return
      * {@code true} even though the file does not have execute permissions.
      *
      * @return  {@code true} if and only if the abstract pathname exists
@@ -2327,7 +2327,7 @@ private synchronized void writeObject(java.io.ObjectOutputStream s)
     /**
      * readObject is called to restore this filename.
      * The original separator character is read.  If it is different
-     * than the separator character on this system, then the old separator
+     * from 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2023, 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
@@ -1093,9 +1093,9 @@ public boolean readBoolean() throws IOException {
     }
 
     /**
-     * Reads an 8 bit byte.
+     * Reads an 8-bit byte.
      *
-     * @return  the 8 bit byte read.
+     * @return  the 8-bit byte read.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
@@ -1104,9 +1104,9 @@ public byte readByte() throws IOException  {
     }
 
     /**
-     * Reads an unsigned 8 bit byte.
+     * Reads an unsigned 8-bit byte.
      *
-     * @return  the 8 bit byte read.
+     * @return  the 8-bit byte read.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
@@ -1115,9 +1115,9 @@ public int readUnsignedByte()  throws IOException {
     }
 
     /**
-     * Reads a 16 bit char.
+     * Reads a 16-bit char.
      *
-     * @return  the 16 bit char read.
+     * @return  the 16-bit char read.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
@@ -1126,9 +1126,9 @@ public char readChar()  throws IOException {
     }
 
     /**
-     * Reads a 16 bit short.
+     * Reads a 16-bit short.
      *
-     * @return  the 16 bit short read.
+     * @return  the 16-bit short read.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
@@ -1137,9 +1137,9 @@ public short readShort()  throws IOException {
     }
 
     /**
-     * Reads an unsigned 16 bit short.
+     * Reads an unsigned 16-bit short.
      *
-     * @return  the 16 bit short read.
+     * @return  the 16-bit short read.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
@@ -1148,9 +1148,9 @@ public int readUnsignedShort() throws IOException {
     }
 
     /**
-     * Reads a 32 bit int.
+     * Reads a 32-bit int.
      *
-     * @return  the 32 bit integer read.
+     * @return  the 32-bit integer read.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
@@ -1159,9 +1159,9 @@ public int readInt()  throws IOException {
     }
 
     /**
-     * Reads a 64 bit long.
+     * Reads a 64-bit long.
      *
-     * @return  the read 64 bit long.
+     * @return  the read 64-bit long.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
@@ -1170,9 +1170,9 @@ public long readLong()  throws IOException {
     }
 
     /**
-     * Reads a 32 bit float.
+     * Reads a 32-bit float.
      *
-     * @return  the 32 bit float read.
+     * @return  the 32-bit float read.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */
@@ -1181,9 +1181,9 @@ public float readFloat() throws IOException {
     }
 
     /**
-     * Reads a 64 bit double.
+     * Reads a 64-bit double.
      *
-     * @return  the 64 bit double read.
+     * @return  the 64-bit double read.
      * @throws  EOFException If end of file is reached.
      * @throws  IOException If other I/O error has occurred.
      */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2023, 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
@@ -768,7 +768,7 @@ public void writeBoolean(boolean val) throws IOException {
     }
 
     /**
-     * Writes an 8 bit byte.
+     * Writes an 8-bit byte.
      *
      * @param   val the byte value to be written
      * @throws  IOException if I/O errors occur while writing to the underlying
@@ -779,7 +779,7 @@ public void writeByte(int val) throws IOException  {
     }
 
     /**
-     * Writes a 16 bit short.
+     * Writes a 16-bit short.
      *
      * @param   val the short value to be written
      * @throws  IOException if I/O errors occur while writing to the underlying
@@ -790,7 +790,7 @@ public void writeShort(int val)  throws IOException {
     }
 
     /**
-     * Writes a 16 bit char.
+     * Writes a 16-bit char.
      *
      * @param   val the char value to be written
      * @throws  IOException if I/O errors occur while writing to the underlying
@@ -801,7 +801,7 @@ public void writeChar(int val)  throws IOException {
     }
 
     /**
-     * Writes a 32 bit int.
+     * Writes a 32-bit int.
      *
      * @param   val the integer value to be written
      * @throws  IOException if I/O errors occur while writing to the underlying
@@ -812,7 +812,7 @@ public void writeInt(int val)  throws IOException {
     }
 
     /**
-     * Writes a 64 bit long.
+     * Writes a 64-bit long.
      *
      * @param   val the long value to be written
      * @throws  IOException if I/O errors occur while writing to the underlying
@@ -823,7 +823,7 @@ public void writeLong(long val)  throws IOException {
     }
 
     /**
-     * Writes a 32 bit float.
+     * Writes a 32-bit float.
      *
      * @param   val the float value to be written
      * @throws  IOException if I/O errors occur while writing to the underlying
@@ -834,7 +834,7 @@ public void writeFloat(float val) throws IOException {
     }
 
     /**
-     * Writes a 64 bit double.
+     * Writes a 64-bit double.
      *
      * @param   val the double value to be written
      * @throws  IOException if I/O errors occur while writing to the underlying

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2023, 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
@@ -226,12 +226,12 @@ public interface ObjectStreamConstants {
     * A Stream Protocol Version. <p>
     *
     * This protocol is written by JVM 1.2.
-    *
+    * <p>
     * Externalizable data is written in block data mode and is
     * terminated with TC_ENDBLOCKDATA. Externalizable class descriptor
     * flags has SC_BLOCK_DATA enabled. JVM 1.1.6 and greater can
     * read this format change.
-    *
+    * <p>
     * Enables writing a nonSerializable class descriptor into the
     * stream. The serialVersionUID of a nonSerializable class is
     * set to 0L.