2003-04-07 Aaron M. Renn (arenn@urbanophile.com)

	* java/io/ObjectStreamException
	* java/io/FileFilter
	* java/io/FilenameFilter
	* java/io/ObjectInput
	* java/io/ObjectOutput
	* java/io/ObjectStreamConstants
	Minor doc fixes, format fixes, spelling corrections, etc.
	* java/io/DataInput
	Corrected code samples in Javadocs to match reality
	* java/io/DataOutput
	* java/io/ObjectInputValidation
	Major documentation fixes - all Javadocs re-written or updated

From-SVN: r65329

libjava/ChangeLog

+2003-04-07  Aaron M. Renn (arenn@urbanophile.com)
+
+	* java/io/ObjectStreamException
+	* java/io/FileFilter
+	* java/io/FilenameFilter
+	* java/io/ObjectInput
+	* java/io/ObjectOutput
+	* java/io/ObjectStreamConstants
+	Minor doc fixes, format fixes, spelling corrections, etc.
+	* java/io/DataInput
+	Corrected code samples in Javadocs to match reality
+	* java/io/DataOutput
+	* java/io/ObjectInputValidation
+	Major documentation fixes - all Javadocs re-written or updated
+
 2003-04-06  Michael Koch  <konqueror@gmx.de>
 
 	* java/net/URLConnection.java:

libjava/java/io/DataInput.java

@@ -84,7 +84,7 @@ public interface DataInput
    * @exception EOFException If end of file is reached before reading the byte
    * @exception IOException If any other error occurs
    *
-   * @see DataOutput
+   * @see DataOutput#writeBoolean
    */
   byte readByte() throws EOFException, IOException;
 
@@ -94,7 +94,7 @@ public interface DataInput
    * <p>
    * This method can read an unsigned byte written by an object 
    * implementing the
-   * <code>writeUnsignedByte()</code> method in the <code>DataOutput</code>
+   * <code>writeByte()</code> method in the <code>DataOutput</code>
    * interface.
    *
    * @return The unsigned bytes value read as a Java <code>int</code>.
@@ -102,7 +102,7 @@ public interface DataInput
    * @exception EOFException If end of file is reached before reading the value
    * @exception IOException If any other error occurs
    *
-   * @see DataOutput
+   * @see DataOutput#writeByte
    */
   int readUnsignedByte() throws EOFException, IOException;
 
@@ -128,7 +128,7 @@ public interface DataInput
    * @exception EOFException If end of file is reached before reading the char
    * @exception IOException If any other error occurs
    *
-   * @see DataOutput
+   * @see DataOutput#writeChar
    */
   char readChar() throws EOFException, IOException;
 
@@ -143,7 +143,7 @@ public interface DataInput
    * first and second byte read from the stream respectively, they will be
    * transformed to a <code>short</code> in the following manner:
    * <p>
-   * <code>(short)((byte1 << 8) + byte2)</code>
+   * <code>(short)((byte1 << 8) + (byte2 & 0xFF))</code>
    * <p>
    * The value returned is in the range of -32768 to 32767.
    * <p>
@@ -157,7 +157,7 @@ public interface DataInput
    * @exception EOFException If end of file is reached before reading the value
    * @exception IOException If any other error occurs
    *
-   * @see DataOutput
+   * @see DataOutput#writeShort
    */
   short readShort() throws EOFException, IOException;
 
@@ -172,12 +172,12 @@ public interface DataInput
    * first and second byte read from the stream respectively, they will be
    * transformed to an <code>int</code> in the following manner:
    * <p>
-   * <code>(int)((byte1 << 8) + byte2)</code>
+   * <code>(int)(((byte1 0xFF) << 8) + (byte2 & 0xFF))</code>
    * <p>
    * The value returned is in the range of 0 to 65535.
    * <p>
    * This method can read an unsigned short written by an object implementing
-   * the <code>writeUnsignedShort()</code> method in the 
+   * the <code>writeShort()</code> method in the 
    * <code>DataOutput</code>
    * interface.
    *
@@ -186,6 +186,8 @@ public interface DataInput
    * @exception EOFException If end of file is reached before reading 
    * the value
    * @exception IOException If any other error occurs
+   *
+   * @see DataOutput#writeShort
    */
   int readUnsignedShort() throws EOFException, IOException;
 
@@ -200,7 +202,8 @@ public interface DataInput
    * the first four bytes read from the stream, they will be
    * transformed to an <code>int</code> in the following manner:
    * <p>
-   * <code>(int)((byte1 << 24) + (byte2 << 16) + (byte3 << 8) + byte4))</code>
+   * <code>(int)(((byte1 & 0xFF) << 24) + ((byte2 & 0xFF) << 16) + 
+   * ((byte3 & 0xFF)<< 8) + (byte4 & 0xFF)))</code>
    * <p>
    * The value returned is in the range of -2147483648 to 2147483647.
    * <p>
@@ -213,7 +216,7 @@ public interface DataInput
    * @exception EOFException If end of file is reached before reading the int
    * @exception IOException If any other error occurs
    *
-   * @see DataOutput
+   * @see DataOutput#writeInt
    */
   int readInt() throws EOFException, IOException;
 
@@ -228,8 +231,10 @@ public interface DataInput
    * the first eight bytes read from the stream, they will be
    * transformed to an <code>long</code> in the following manner:
    * <p>
-   * <code>(long)((byte1 << 56) + (byte2 << 48) + (byte3 << 40) + 
-   * (byte4 << 32) + (byte5 << 24) + (byte6 << 16) + (byte7 << 8) + byte9))
+   * <code>(long)(((byte1 & 0xFF) << 56) + ((byte2 & 0xFF) << 48) + 
+   * ((byte3 & 0xFF) << 40) + ((byte4 & 0xFF) << 32) + 
+   * ((byte5 & 0xFF) << 24) + ((byte6 & 0xFF) << 16) + 
+   * ((byte7 & 0xFF) << 8) + (byte9 & 0xFF)))
    * </code>
    * <p>
    * The value returned is in the range of -9223372036854775808 to
@@ -244,7 +249,7 @@ public interface DataInput
    * @exception EOFException If end of file is reached before reading the long
    * @exception IOException If any other error occurs
    *
-   * @see DataOutput
+   * @see DataOutput#writeLong
    */
   long readLong() throws EOFException, IOException;
 
@@ -267,8 +272,8 @@ public interface DataInput
    * float
    * @exception IOException If any other error occurs
    *
-   * @see java.lang.Float
-   * @see DataOutput
+   * @see DataOutput#writeFloat
+   * @see java.lang.Float#intBitsToFloat
    */
   float readFloat() throws EOFException, IOException;
 
@@ -290,8 +295,8 @@ public interface DataInput
    * double
    * @exception IOException If any other error occurs
    *
-   * @see java.lang.Double
-   * @see DataOutput
+   * @see DataOutput#writeDouble
+   * @see java.lang.Double#longBitsToDouble
    */
   double readDouble() throws EOFException, IOException;
 
@@ -309,6 +314,7 @@ public interface DataInput
    * A line terminator is a byte sequence consisting of either 
    * <code>\r</code>, <code>\n</code> or <code>\r\n</code>.  These termination
    * charaters are discarded and are not returned as part of the string.
+   * A line is also terminated by an end of file condition.
    * <p>
    * This method can read data that was written by an object implementing the
    * <code>writeLine()</code> method in <code>DataOutput</code>.
@@ -317,7 +323,7 @@ public interface DataInput
    *
    * @exception IOException If an error occurs
    *
-   * @see DataOutput
+   * @see DataOutput#writeLine
    */
   String readLine() throws IOException;
 
@@ -390,7 +396,7 @@ public interface DataInput
    * @exception UTFDataFormatException If the data is not in UTF-8 format
    * @exception IOException If any other error occurs
    *
-   * @see DataOutput
+   * @see DataOutput#writeUTF
    */
   String readUTF() throws EOFException, UTFDataFormatException, IOException;
 
@@ -398,7 +404,9 @@ public interface DataInput
    * This method reads raw bytes into the passed array until the array is
    * full.  Note that this method blocks until the data is available and
    * throws an exception if there is not enough data left in the stream to
-   * fill the buffer
+   * fill the buffer.  Note also that zero length buffers are permitted.
+   * In this case, the method will return immediately without reading any
+   * bytes from the stream.
    *
    * @param buf The buffer into which to read the data
    *
@@ -414,8 +422,10 @@ public interface DataInput
    * <code>offset</code> bytes into the buffer.  The number of bytes read 
    * will be
    * exactly <code>len</code>.  Note that this method blocks until the data is 
-   * available and * throws an exception if there is not enough data left in 
-   * the stream to read <code>len</code> bytes.
+   * available and throws an exception if there is not enough data left in 
+   * the stream to read <code>len</code> bytes.  Note also that zero length
+   * buffers are permitted.  In this case, the method will return immediately
+   * without reading any bytes from the stream.
    *
    * @param buf The buffer into which to read the data
    * @param offset The offset into the buffer to start storing data
@@ -430,17 +440,18 @@ public interface DataInput
 
   /**
    * This method skips and discards the specified number of bytes in an
-   * input stream
+   * input stream.  Note that this method may skip less than the requested
+   * number of bytes.  The actual number of bytes skipped is returned.
    *
-   * @param num_bytes The number of bytes to skip
+   * @param numBytes The number of bytes to skip
    *
    * @return The number of bytes actually skipped, which will always be
-   *         <code>num_bytes</code>
+   *         <code>numBytes</code>
    *
    * @exception EOFException If end of file is reached before all bytes can be
    *                         skipped
    * @exception IOException If any other error occurs
    */
-  int skipBytes(int n) throws EOFException, IOException;
+  int skipBytes(int numBytes) throws EOFException, IOException;
 
 } // interface DataInput

libjava/java/io/FileFilter.java

 /* FileFilter.java -- Filter a list of pathnames
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998,2003 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -41,12 +41,14 @@ package java.io;
 /**
  * This interface has one method which is used for filtering pathnames
  * returned in a pathname listing.  It is currently used by the 
- * <code>File.listFiles()</code> method.
+ * <code>File.listFiles(FileFilter)</code> method.
  * <p>
  * The method in this interface determines if a particular pathname should
  * or should not be included in the pathname listing.
  *
  * @author Aaron M. Renn (arenn@urbanophile.com)
+ * 
+ * @see File#listFiles(java.io.FileFilter)
  */
 public interface FileFilter
 {

libjava/java/io/FilenameFilter.java

 /* FilenameFilter.java -- Filter a list of filenames
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -46,17 +46,20 @@ package java.io;
 /**
  * This interface has one method which is used for filtering filenames
  * returned in a directory listing.  It is currently used by the 
- * <code>File.list()</code> method and by the filename dialog in AWT.
+ * <code>File.list(FilenameFilter)</code> method and by the filename 
+ * dialog in AWT.
  * <p>
  * The method in this interface determines if a particular file should
  * or should not be included in the file listing.
  *
  * @author Aaron M. Renn (arenn@urbanophile.com)
  * @author Tom Tromey <tromey@cygnus.com>
+ *
+ * @see File#listFiles(java.io.FilenameFilter)
+ * @see java.awt.FileDialog#setFilenameFilter(java.io.FilenameFilter)
  */
 public interface FilenameFilter
 {
-
   /**
    * This method determines whether or not a given file should be included
    * in a directory listing.

libjava/java/io/ObjectInput.java

@@ -45,6 +45,8 @@ package java.io;
   * <code>InputStream</code>
   *
   * @author Aaron M. Renn (arenn@urbanophile.com)
+  *
+  * @see DataInput
   */
 public interface ObjectInput extends DataInput
 {
@@ -60,7 +62,8 @@ public interface ObjectInput extends DataInput
 
   /**
     * This method reading a byte of data from a stream.  It returns that byte
-    * as an int.  This method blocks if no data is available to be read.
+    * as an <code>int</code>.  This method blocks if no data is available 
+    * to be read.
     * 
     * @return The byte of data read
     *
@@ -76,7 +79,7 @@ public interface ObjectInput extends DataInput
     *
     * @param buf The byte array to receive the data read
     *
-    * @return The actual number fo bytes read or -1 if end of stream
+    * @return The actual number of bytes read or -1 if end of stream
     *
     * @exception IOException If an error occurs
     */
@@ -92,10 +95,10 @@ public interface ObjectInput extends DataInput
     * possible.
     *
     * @param buf The byte array to receive the data read
-    * @param offset The offset into @code{buf} to start storing data
+    * @param offset The offset into <code>buf</code> to start storing data
     * @param len The maximum number of bytes to read
     *
-    * @return The actual number fo bytes read or -1 if end of stream
+    * @return The actual number of bytes read or -1 if end of stream
     *
     * @exception IOException If an error occurs
     */
@@ -103,14 +106,14 @@ public interface ObjectInput extends DataInput
 
   /**
     * Reads an object instance and returns it.  If the class for the object
-    * being read cannot be found, then a ClassNotFoundException will
-    * be thrown.
+    * being read cannot be found, then a <code>ClassNotFoundException</code>
+    * will be thrown.
     *
     * @return The object instance that was read
     *
     * @exception ClassNotFoundException If a class for the object cannot be 
     * found
-    * @exception IOException If an error occurs
+    * @exception IOException If any other error occurs
     */
   public abstract Object readObject() 
     throws ClassNotFoundException, IOException;
@@ -126,7 +129,7 @@ public interface ObjectInput extends DataInput
     *
     * @exception IOException If an error occurs
     */
-  public abstract long skip(long num_bytes) throws IOException;
+  public abstract long skip(long numBytes) throws IOException;
 
   /**
     * This method closes the input source

libjava/java/io/ObjectInputValidation.java

@@ -39,16 +39,27 @@ exception statement from your version. */
 package java.io; 
 
 /**
-  * What does this interface really do?
+  * This class allows an object to validate that it is valid after
+  * deserialization has run completely for it and all dependent objects.
+  * This allows an object to determine if it is invalid even if all
+  * state data was correctly deserialized from the stream.  It can also
+  * be used to perform re-initialization type activities on an object
+  * after it has been completely deserialized.
+  *
+  * Since this method functions as a type of callback, it must be 
+  * registered through <code>ObjectInputStream.registerValidation</code>
+  * in order to be invoked.  This is typically done in the
+  * <code>readObject</code> method.
   *
   * @author Aaron M. Renn (arenn@urbanophile.com)
+  *
+  * @see ObjectInputStream#registerValidation
   */
 public interface ObjectInputValidation
 {
-
   /**
-    * This method is called to validate an object.  If the object is invalid
-    * an exception is thrown.
+    * This method is called to validate an object after serialization
+    * is complete.  If the object is invalid an exception is thrown.
     *
     * @exception InvalidObjectException If the object is invalid
     */

libjava/java/io/ObjectOutput.java

@@ -45,10 +45,11 @@ package java.io;
   * <code>OutputStream</code> like.
   *
   * @author Aaron M. Renn (arenn@urbanophile.com)
+  *
+  * @see DataOutput
   */
 public interface ObjectOutput extends DataOutput
 {
-
   /**
     * This method writes the specified byte to the output stream.
     *

libjava/java/io/ObjectStreamConstants.java

 /* ObjectStreamConstants.java -- Interface containing constant values
    used in reading and writing serialized objects
-   Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2003 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,14 +40,15 @@ exception statement from your version. */
 package java.io;
 
 /**
-   This interface contains constants that are used in object
-   serialization.  This interface is used by ObjectOutputStream,
-   ObjectInputStream, ObjectStreamClass, and possibly other classes.
-   The values for these constants are specified in Javasoft's "Object
-   Serialization Specification" TODO: add reference
-*/
+ * This interface contains constants that are used in object
+ * serialization.  This interface is used by <code>ObjectOutputStream</code>,
+ * <code>ObjectInputStream</code>, and <code>ObjectStreamClass</code>.
+ * The values for these constants are specified by the Java library
+ * specification.
+ */
 public interface ObjectStreamConstants
 {
+  // FIXME: Javadoc comment these values.
   public final static int PROTOCOL_VERSION_1 = 1;
   public final static int PROTOCOL_VERSION_2 = 2;
 
@@ -85,3 +86,4 @@ public interface ObjectStreamConstants
   final static SerializablePermission SUBCLASS_IMPLEMENTATION_PERMISSION
     = new SerializablePermission("enableSubclassImplementation");
 }
+

libjava/java/io/ObjectStreamException.java

 /* ObjectStreamException.java -- Superclass of all serialization exceptions
-   Copyright (C) 1998, 2000, 2001, 2002 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,7 +40,7 @@ package java.io;
 
 /**
  * This exception is thrown when a problem occurs during serialization.
- * There are more specific subclasses than give more fine grained
+ * There are more specific subclasses that give more fine grained
  * indications of the precise failure.
  *
  * @author Aaron M. Renn (arenn@urbanophile.com)