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/DataOutput.java

 /* DataOutput.java -- Interface for writing data from a stream
-   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.
 
@@ -45,119 +45,254 @@ package java.io;
 
 /**
  * This interface is implemented by classes that can wrte data to streams 
- * from Java primitive types.
+ * from Java primitive types.  This data can subsequently be read back
+ * by classes implementing the <code>DataInput</code> interface. 
  *
  * @author Aaron M. Renn (arenn@urbanophile.com)
  * @author Tom Tromey <tromey@cygnus.com>
+ *
+ * @see DataInput
  */
 public interface DataOutput
 {
-
   /**
-   * This method writes a Java boolean value to an output stream
+   * This method writes a Java boolean value to an output stream.  If
+   * <code>value</code> is <code>true</code>, a byte with the value of
+   * 1 will be written, otherwise a byte with the value of 0 will be 
+   * written.
+   *
+   * The value written can be read using the <code>readBoolean</code>
+   * method in <code>DataInput</code>.
    *
    * @param value The boolean value to write
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readBoolean
    */
   void writeBoolean(boolean value) throws IOException;
 
   /**
-   * This method writes a Java byte value to an output stream
+   * This method writes a Java byte value to an output stream.  The
+   * byte to be written will be in the lowest 8 bits of the 
+   * <code>int</code> value passed.
+   *
+   * The value written can be read using the <code>readByte</code> or
+   * <code>readUnsignedByte</code> methods in <code>DataInput</code>.
    *
    * @param value The int value to write
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readByte
+   * @see DataInput#readUnsignedByte
    */
   void writeByte(int value) throws IOException;
 
   /**
-   * This method writes a Java char value to an output stream
+   * This method writes a Java char value to an output stream.  The
+   * char to be written will be in the lowest 16 bits of the <code>int</code>
+   * value passed.  These bytes will be written "big endian".  That is,
+   * with the high byte written first in the following manner:
+   * <p>
+   * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br>
+   * byte1 = (byte)(value & 0x00FF);</code>
+   * <p>
+   *
+   * The value written can be read using the <code>readChar</code>
+   * method in <code>DataInput</code>.
    *
    * @param value The char value to write
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readChar
    */
   void writeChar(int value) throws IOException;
 
   /**
-   * This method writes a Java int value to an output stream as a 16 bit value
+   * This method writes a Java char value to an output stream.  The
+   * char to be written will be in the lowest 16 bits of the <code>int</code>
+   * value passed.  These bytes will be written "big endian".  That is,
+   * with the high byte written first in the following manner:
+   * <p>
+   * <code>byte0 = (byte)((value & 0xFF00) >> 8);<br>
+   * byte1 = (byte)(value & 0x00FF);</code>
+   * <p>
+   *
+   * The value written can be read using the <code>readShort</code> and
+   * <code>readUnsignedShort</code> methods in <code>DataInput</code>.
    *
    * @param value The int value to write as a 16-bit value
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readShort
+   * @see DataInput#readUnsignedShort
    */
   void writeShort(int value) throws IOException;
 
   /**
-   * This method writes a Java int value to an output stream
+   * This method writes a Java int value to an output stream.  The 4 bytes
+   * of the passed value will be written "big endian".  That is, with
+   * the high byte written first in the following manner:
+   * <p>
+   * <code>byte0 = (byte)((value & 0xFF000000) >> 24);<br>
+   * byte1 = (byte)((value & 0x00FF0000) >> 16);<br>
+   * byte2 = (byte)((value & 0x0000FF00) >> 8);<br>
+   * byte3 = (byte)(value & 0x000000FF);</code>
+   * <p>
+   *
+   * The value written can be read using the <code>readInt</code>
+   * method in <code>DataInput</code>.
    *
    * @param value The int value to write
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readInt
    */
   void writeInt(int value) throws IOException;
 
   /**
-   * This method writes a Java long value to an output stream
+   * This method writes a Java long value to an output stream.  The 8 bytes
+   * of the passed value will be written "big endian".  That is, with
+   * the high byte written first in the following manner:
+   * <p>
+   * <code>byte0 = (byte)((value & 0xFF00000000000000L) >> 56);<br>
+   * byte1 = (byte)((value & 0x00FF000000000000L) >> 48);<br>
+   * byte2 = (byte)((value & 0x0000FF0000000000L) >> 40);<br>
+   * byte3 = (byte)((value & 0x000000FF00000000L) >> 32);<br>
+   * byte4 = (byte)((value & 0x00000000FF000000L) >> 24);<br>
+   * byte5 = (byte)((value & 0x0000000000FF0000L) >> 16);<br>
+   * byte6 = (byte)((value & 0x000000000000FF00L) >> 8);<br>
+   * byte7 = (byte)(value & 0x00000000000000FFL);</code>
+   * <p>
+   *
+   * The value written can be read using the <code>readLong</code>
+   * method in <code>DataInput</code>.
    *
    * @param value The long value to write
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readLong
    */
   void writeLong(long value) throws IOException;
 
   /**
-   * This method writes a Java float value to an output stream
+   * This method writes a Java <code>float</code> value to the stream.  This
+   * value is written by first calling the method
+   * <code>Float.floatToIntBits</code>
+   * to retrieve an <code>int</code> representing the floating point number,
+   * then writing this <code>int</code> value to the stream exactly the same
+   * as the <code>writeInt()</code> method does.
+   *
+   * The value written can be read using the <code>readFloat</code>
+   * method in <code>DataInput</code>.
    *
    * @param value The float value to write
    *
    * @exception IOException If an error occurs
+   *
+   * @see writeInt
+   * @see DataInput#readFloat
+   * @see Float#floatToIntBits
    */
   void writeFloat(float value) throws IOException;
 
   /**
-   * This method writes a Java double value to an output stream
+   * This method writes a Java <code>double</code> value to the stream.  This
+   * value is written by first calling the method
+   * <code>Double.doubleToLongBits</code>
+   * to retrieve an <code>long</code> representing the floating point number,
+   * then writing this <code>long</code> value to the stream exactly the same
+   * as the <code>writeLong()</code> method does.
+   *
+   * The value written can be read using the <code>readDouble</code>
+   * method in <code>DataInput</code>.
    *
    * @param value The double value to write
    *
    * @exception IOException If any other error occurs
+   *
+   * @see writeLong
+   * @see DataInput#readDouble
+   * @see Double#doubleToLongBits
    */
   void writeDouble(double value) throws IOException;
 
   /**
-   * This method writes a String to an output stream as an array of bytes
+   * This method writes all the bytes in a <code>String</code> out to the
+   * stream.  One byte is written for each character in the
+   * <code>String</code>.
+   * The high eight bits of each character are discarded, thus this
+   * method is inappropriate for completely representing Unicode characters.
    *
-   * @param value The String to write
+   * @param value The <code>String</code> to write
    *
    * @exception IOException If an error occurs
    */
   void writeBytes(String value) throws IOException;
 
   /**
-   * This method writes a String to an output stream as an array of char's
+   * This method writes all the bytes of a <code>String</code> to an 
+   * output stream as an array of <code>char</code>'s. Each character
+   * is written using the method specified in the <code>writeChar</code>
+   * method. 
    *
    * @param value The String to write
    *
    * @exception IOException If an error occurs
+   *
+   * @see writeChar
    */
   void writeChars(String value) throws IOException;
 
   /**
-   * This method writes a String to an output stream encoded in
-   * UTF-8 format.
+  * This method writes a Java <code>String</code> to the stream in a modified
+   * UTF-8 format.  First, two bytes are written to the stream indicating the
+   * number of bytes to follow.  This is written in the form of a Java
+   * <code>short</code> value in the same manner used by the 
+   * <code>writeShort</code> method.  Note that this is the number of 
+   * bytes in the
+   * encoded <code>String</code> not the <code>String</code> length.  Next
+   * come the encoded characters.  Each character in the <code>String</code>
+   * is encoded as either one, two or three bytes.  For characters in the
+   * range of <code>\u0001</code> to <code>\u007F</code>, one byte is used.  
+   * The character
+   * value goes into bits 0-7 and bit eight is 0.  For characters in the range
+   * of <code>\u0080</code> to <code>\u007FF</code>, two bytes are used.  Bits
+   * 6-10 of the character value are encoded bits 0-4 of the first byte, with
+   * the high bytes having a value of "110".  Bits 0-5 of the character value
+   * are stored in bits 0-5 of the second byte, with the high bits set to
+   * "10".  This type of encoding is also done for the null character
+   * <code>\u0000</code>.  This eliminates any C style NUL character values
+   * in the output.  All remaining characters are stored as three bytes.
+   * Bits 12-15 of the character value are stored in bits 0-3 of the first
+   * byte.  The high bits of the first bytes are set to "1110".  Bits 6-11
+   * of the character value are stored in bits 0-5 of the second byte.  The
+   * high bits of the second byte are set to "10".  And bits 0-5 of the
+   * character value are stored in bits 0-5 of byte three, with the high bits
+   * of that byte set to "10".
    *
-   * @param value The String to write
+   * The value written can be read using the <code>readUTF</code>
+   * method in <code>DataInput</code>.
+   *
+   * @param value The <code>String</code> to write
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readUTF
    */
   void writeUTF(String value) throws IOException;
 
   /**
    * This method writes an 8-bit value (passed into the method as a Java
-   * int) to an output stream.
+   * <code>int</code>) to an output stream.  The low 8 bits of the
+   * passed value are written.
    *
-   * @param value The byte to write to the output stream
+   * @param value The <code>byte</code> to write to the output stream
    *
    * @exception IOException If an error occurs
    */
@@ -176,7 +311,7 @@ public interface DataOutput
    * This method writes raw bytes from the passed array <code>buf</code> 
    * starting
    * <code>offset</code> bytes into the buffer.  The number of bytes 
-   * written will be * exactly <code>len</code>. 
+   * written will be exactly <code>len</code>. 
    *
    * @param buf The buffer from which to write the data
    * @param offset The offset into the buffer to start writing data from

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)