* java/io/StringWriter.java: Merged with Classpath.

	* java/io/InputStream.java: Merged with Classpath.
	* java/io/OutputStream.java: Merged with Classpath.
	* java/io/PushbackInputStream.java: Merged with Classpath.
	* java/io/CharArrayReader.java: Merged with Classpath.
	* java/io/CharArrayWriter.java: Merged with Classpath.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@44652 138bc75d-0d04-0410-961f-82ee72b054a4

7 files changed, 979 insertions, 179 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index 4eb7694b79f..c32cf36d691 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,3 +1,12 @@
+2001-08-05  Tom Tromey  <tromey@redhat.com>
+
+	* java/io/StringWriter.java: Merged with Classpath.
+	* java/io/InputStream.java: Merged with Classpath.
+	* java/io/OutputStream.java: Merged with Classpath.
+	* java/io/PushbackInputStream.java: Merged with Classpath.
+	* java/io/CharArrayReader.java: Merged with Classpath.
+	* java/io/CharArrayWriter.java: Merged with Classpath.
+
 2001-08-02  Tom Tromey  <tromey@redhat.com>
 
 	* prims.cc (JNI_OnLoad): Don't declare.
diff --git a/libjava/java/io/CharArrayReader.java b/libjava/java/io/CharArrayReader.java
index d67c7c79f5c..4d4fca7fe65 100644
--- a/libjava/java/io/CharArrayReader.java
+++ b/libjava/java/io/CharArrayReader.java
@@ -1,43 +1,103 @@
-/* Copyright (C) 1998, 1999, 2001  Free Software Foundation
+/* CharArrayReader.java -- Read an array of characters as a stream
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
-   This file is part of libgcj.
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+ 
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
  
 package java.io;
 
 /**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date October 16, 1998.  
- */
-
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct
- */
- 
+  * This class permits an array of chars to be read as an input stream.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Warren Levy <warrenl@cygnus.com>
+  */
 public class CharArrayReader extends Reader
 {
-  /* An array of chars provided by the creator of the stream. */
+  /**
+   * The array that contains the data supplied during read operations
+   */
   protected char[] buf;
 
-  /* Position of the next char in buf to be read. */
+  /**
+   * The array index of the next char to be read from the buffer
+   * <code>buf</code>
+   */
   protected int pos;
 
-  /* The currently marked position in the stream. */
+  /**
+   * The currently marked position in the stream.  This defaults to 0, so a
+   * reset operation on the stream resets it to read from array index 0 in
+   * the buffer - even if the stream was initially created with an offset
+   * greater than 0
+   */
   protected int markedPos;
 
-  /* The index in buf one greater than the last valid character. */
+  /**
+   * This indicates the maximum number of chars that can be read from this
+   * stream.  It is the array index of the position after the last valid
+   * char in the buffer <code>buf</code>
+   */
   protected int count;
 
+  /**
+   * Create a new CharArrayReader that will read chars from the passed
+   * in char array.  This stream will read from the beginning to the end
+   * of the array.  It is identical to calling an overloaded constructor
+   * as <code>CharArrayReader(buf, 0, buf.length)</code>.
+   * <p>
+   * Note that this array is not copied.  If its contents are changed 
+   * while this stream is being read, those changes will be reflected in the
+   * chars supplied to the reader.  Please use caution in changing the 
+   * contents of the buffer while this stream is open.
+   *
+   * @param buffer The char array buffer this stream will read from.
+  */
   public CharArrayReader(char[] buffer)
   {
     this(buffer, 0, buffer.length);
   }
 
+  /**
+   * Create a new CharArrayReader that will read chars from the passed
+   * in char array.  This stream will read from position
+   * <code>offset</code> in the array for a length of
+   * <code>length</code> chars past <code>offset</code>.  If the
+   * stream is reset to a position before <code>offset</code> then
+   * more than <code>length</code> chars can be read from the stream.
+   * The <code>length</code> value should be viewed as the array index
+   * one greater than the last position in the buffer to read.
+   * <p>
+   * Note that this array is not copied.  If its contents are changed 
+   * while this stream is being read, those changes will be reflected in the
+   * chars supplied to the reader.  Please use caution in changing the 
+   * contents of the buffer while this stream is open.
+   *
+   * @param buffer The char array buffer this stream will read from.
+   * @param offset The index into the buffer to start reading chars from
+   * @param length The number of chars to read from the buffer
+   */
   public CharArrayReader(char[] buffer, int offset, int length)
   {
     super();
@@ -54,72 +114,130 @@ public class CharArrayReader extends Reader
     markedPos = pos;
   }
 
+  /**
+   * This method closes the stream.
+   */
   public void close()
   {
     synchronized (lock)
-    {
-      buf = null;
-    }
+      {
+	buf = null;
+      }
   }
 
+  /**
+   * This method sets the mark position in this stream to the current
+   * position.  Note that the <code>readlimit</code> parameter in this
+   * method does nothing as this stream is always capable of
+   * remembering all the chars int it.
+   * <p>
+   * Note that in this class the mark position is set by default to
+   * position 0 in the stream.  This is in constrast to some other
+   * stream types where there is no default mark position.
+   *
+   * @param readAheadLimit The number of chars this stream must
+   *                       remember.  This parameter is ignored.
+   *
+   * @exception IOException If an error occurs
+   */
   public void mark(int readAheadLimit) throws IOException
   {
     synchronized (lock)
-    {
-      if (buf == null)
-	throw new IOException("Stream closed");
-      // readAheadLimit is ignored per Java Class Lib. book, p. 318.
-      markedPos = pos;
-    }
+      {
+	if (buf == null)
+	  throw new IOException("Stream closed");
+	// readAheadLimit is ignored per Java Class Lib. book, p. 318.
+	markedPos = pos;
+      }
   }
 
+  /**
+   * This method overrides the <code>markSupported</code> method in
+   * <code>Reader</code> in order to return <code>true</code> -
+   * indicating that this stream class supports mark/reset
+   * functionality.
+   *
+   * @return <code>true</code> to indicate that this class supports
+   * mark/reset.
+   */
   public boolean markSupported()
   {
     return true;
   }
 
+  /**
+   * This method reads one char from the stream.  The <code>pos</code>
+   * counter is advanced to the next char to be read.  The char read
+   * is returned as an int in the range of 0-65535.  If the stream
+   * position is already at the end of the buffer, no char is read and
+   * a -1 is returned in order to indicate the end of the stream.
+   *
+   * @return The char read, or -1 if end of stream
+   */
   public int read() throws IOException
   {
     synchronized (lock)
-    {
-      if (buf == null)
-	throw new IOException("Stream closed");
+      {
+	if (buf == null)
+	  throw new IOException("Stream closed");
 
-      if (pos < 0)
-        throw new ArrayIndexOutOfBoundsException(pos);
+	if (pos < 0)
+	  throw new ArrayIndexOutOfBoundsException(pos);
 
-      if (pos < count)
-        return ((int) buf[pos++]) & 0xFFFF;
-      return -1;
-    }
+	if (pos < count)
+	  return ((int) buf[pos++]) & 0xFFFF;
+	return -1;
+      }
   }
 
+  /**
+   * This method reads chars from the stream and stores them into a
+   * caller supplied buffer.  It starts storing the data at index
+   * <code>offset</code> into the buffer and attempts to read
+   * <code>len</code> chars.  This method can return before reading
+   * the number of chars requested if the end of the stream is
+   * encountered first.  The actual number of chars read is returned.
+   * If no chars can be read because the stream is already at the end
+   * of stream position, a -1 is returned.
+   * <p>
+   * This method does not block.
+   *
+   * @param b The array into which the chars read should be stored.
+   * @param off The offset into the array to start storing chars
+   * @param len The requested number of chars to read
+   *
+   * @return The actual number of chars read, or -1 if end of stream.
+   */
   public int read(char[] b, int off, int len) throws IOException
   {
     synchronized (lock)
-    {
-      if (buf == null)
-	throw new IOException("Stream closed");
-
-      /* Don't need to check pos value, arraycopy will check it. */
-      if (off < 0 || len < 0 || off + len > b.length)
-        throw new ArrayIndexOutOfBoundsException();
-
-      if (pos >= count)
-        return -1;
-
-      int numChars = Math.min(count - pos, len);
-      System.arraycopy(buf, pos, b, off, numChars);
-      pos += numChars;
-      return numChars;
-    }
+      {
+	if (buf == null)
+	  throw new IOException("Stream closed");
+
+	/* Don't need to check pos value, arraycopy will check it. */
+	if (off < 0 || len < 0 || off + len > b.length)
+	  throw new ArrayIndexOutOfBoundsException();
+
+	if (pos >= count)
+	  return -1;
+
+	int numChars = Math.min(count - pos, len);
+	System.arraycopy(buf, pos, b, off, numChars);
+	pos += numChars;
+	return numChars;
+      }
   }
 
-  /** Return true if more characters are available to be read. 
-    *
-    * @specnote The JDK 1.3 API docs are wrong here. This method will
-    *           return false if there are no more characters available.
-    */
+  /**
+   * Return true if more characters are available to be read. 
+   *
+   * @return <code>true</code> to indicate that this stream is ready
+   * to be read.
+   *
+   * @specnote The JDK 1.3 API docs are wrong here. This method will
+   *           return false if there are no more characters available.
+   */
   public boolean ready() throws IOException
   {
     if (buf == null)
@@ -128,31 +246,49 @@ public class CharArrayReader extends Reader
     return (pos < count);
   }
 
+  /**
+   * This method sets the read position in the stream to the mark
+   * point by setting the <code>pos</code> variable equal to the
+   * <code>mark</code> variable.  Since a mark can be set anywhere in
+   * the array, the mark/reset methods int this class can be used to
+   * provide random search capabilities for this type of stream.
+   */
   public void reset() throws IOException
   {
     synchronized (lock)
-    {
-      if (buf == null)
-	throw new IOException("Stream closed");
+      {
+	if (buf == null)
+	  throw new IOException("Stream closed");
 
-      pos = markedPos;
-    }
+	pos = markedPos;
+      }
   }
 
+  /**
+   * This method attempts to skip the requested number of chars in the
+   * input stream.  It does this by advancing the <code>pos</code> value by the
+   * specified number of chars.  It this would exceed the length of the
+   * buffer, then only enough chars are skipped to position the stream at
+   * the end of the buffer.  The actual number of chars skipped is returned.
+   *
+   * @param n The requested number of chars to skip
+   *
+   * @return The actual number of chars skipped.
+   */
   public long skip(long n) throws IOException
   {
     synchronized (lock)
-    {
-      if (buf == null)
-	throw new IOException("Stream closed");
-
-      // Even though the var numChars is a long, in reality it can never
-      // be larger than an int since the result of subtracting 2 positive
-      // ints will always fit in an int.  Since we have to return a long
-      // anyway, numChars might as well just be a long.
-      long numChars = Math.min((long) (count - pos), n < 0 ? 0L : n);
-      pos += numChars;
-      return numChars;
-    }
+      {
+	if (buf == null)
+	  throw new IOException("Stream closed");
+
+	// Even though the var numChars is a long, in reality it can never
+	// be larger than an int since the result of subtracting 2 positive
+	// ints will always fit in an int.  Since we have to return a long
+	// anyway, numChars might as well just be a long.
+	long numChars = Math.min((long) (count - pos), n < 0 ? 0L : n);
+	pos += numChars;
+	return numChars;
+      }
   }
 }
diff --git a/libjava/java/io/CharArrayWriter.java b/libjava/java/io/CharArrayWriter.java
index 7bec5558a01..44db842fde5 100644
--- a/libjava/java/io/CharArrayWriter.java
+++ b/libjava/java/io/CharArrayWriter.java
@@ -1,43 +1,98 @@
-// CharArrayWriter.java - Character array output stream.
+/* CharArrayWriter.java -- Write chars to a buffer
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
-/* Copyright (C) 1998, 1999, 2001  Free Software Foundation
+This file is part of GNU Classpath.
 
-   This file is part of libgcj.
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+ 
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
 
-package java.io;
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
 
-/**
- * @author Tom Tromey <tromey@cygnus.com>
- * @date September 25, 1998 
- */
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * Status:  Complete to 1.1.
- */
+package java.io;
 
+/**
+  * This class allows data to be written to a char array buffer and
+  * and then retrieved by an application.   The internal char array
+  * buffer is dynamically resized to hold all the data written.  Please
+  * be aware that writing large amounts to data to this stream will
+  * cause large amounts of memory to be allocated.
+  * <p>
+  * The size of the internal buffer defaults to 32 and it is resized
+  * in increments of 1024 chars.  This behavior can be over-ridden by using the
+  * following two properties:
+  * <p>
+  * <ul>
+  * <li><xmp>gnu.java.io.CharArrayWriter.initialBufferSize</xmp>
+  * <li><xmp>gnu.java.io.CharArrayWriter.bufferIncrementSize</xmp>
+  * </ul>
+  * <p>
+  * There is a constructor that specified the initial buffer size and
+  * that is the preferred way to set that value because it it portable
+  * across all Java class library implementations.
+  * <p>
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Tom Tromey <tromey@cygnus.com>
+  */
 public class CharArrayWriter extends Writer
 {
+  /**
+   * The default initial buffer size
+   */
+  private static final int DEFAULT_INITIAL_BUFFER_SIZE = 32;
+
+  /**
+   * This method initializes a new <code>CharArrayWriter</code> with
+   * the default buffer size of 32 chars.  If a different initial
+   * buffer size is desired, see the constructor
+   * <code>CharArrayWriter(int size)</code>.
+   */
   public CharArrayWriter ()
   {
-    this (32);
+    this (DEFAULT_INITIAL_BUFFER_SIZE);
   }
 
+  /**
+   * This method initializes a new <code>CharArrayWriter</code> with
+   * a specified initial buffer size.
+   *
+   * @param size The initial buffer size in chars
+   */
   public CharArrayWriter (int size)
   {
     super ();
     buf = new char[size];
   }
 
+  /**
+   * Closes the stream.  This method is guaranteed not to free the contents
+   * of the internal buffer, which can still be retrieved.
+   */
   public void close ()
   {
     closed = true;
   }
 
+  /**
+   * This method flushes all buffered chars to the stream.
+   */
   public void flush () throws IOException
   {
     synchronized (lock)
@@ -47,6 +102,11 @@ public class CharArrayWriter extends Writer
       }
   }
 
+  /**
+   * This method discards all of the chars that have been written to the
+   * internal buffer so far by setting the <code>count</code> variable to
+   * 0.  The internal buffer remains at its currently allocated size.
+   */
   public void reset ()
   {
     synchronized (lock)
@@ -58,11 +118,31 @@ public class CharArrayWriter extends Writer
       }
   }
 
+  /**
+   * This method returns the number of chars that have been written to
+   * the buffer so far.  This is the same as the value of the protected
+   * <code>count</code> variable.  If the <code>reset</code> method is
+   * called, then this value is reset as well.  Note that this method does
+   * not return the length of the internal buffer, but only the number
+   * of chars that have been written to it.
+   *
+   * @return The number of chars in the internal buffer
+   *
+   * @see reset
+   */
   public int size ()
   {
     return count;
   }
 
+  /**
+   * This method returns a char array containing the chars that have been
+   * written to this stream so far.  This array is a copy of the valid
+   * chars in the internal buffer and its length is equal to the number of
+   * valid chars, not necessarily to the the length of the current 
+   * internal buffer.  Note that since this method allocates a new array,
+   * it should be used with caution when the internal buffer is very large.
+   */
   public char[] toCharArray ()
   {
     synchronized (lock)
@@ -73,6 +153,15 @@ public class CharArrayWriter extends Writer
       }
   }
 
+  /**
+   * Returns the chars in the internal array as a <code>String</code>.  The
+   * chars in the buffer are converted to characters using the system default
+   * encoding.  There is an overloaded <code>toString()</code> method that
+   * allows an application specified character encoding to be used.
+   *
+   * @return A <code>String</code> containing the data written to this
+   *         stream so far
+   */
   public String toString ()
   {
     synchronized (lock)
@@ -81,6 +170,12 @@ public class CharArrayWriter extends Writer
       }
   }
 
+  /**
+   * This method writes the writes the specified char into the internal
+   * buffer.
+   *
+   * @param oneChar The char to be read passed as an int
+   */
   public void write (int oneChar) throws IOException
   {
     synchronized (lock)
@@ -93,6 +188,14 @@ public class CharArrayWriter extends Writer
       }
   }
 
+  /**
+   * This method writes <code>len</code> chars from the passed in array 
+   * <code>buf</code> starting at index <code>offset</code> into that buffer
+   *
+   * @param buffer The char array to write data from
+   * @param offset The index into the buffer to start writing data from
+   * @param len The number of chars to write
+   */
   public void write (char[] buffer, int offset, int len) throws IOException
   {
     synchronized (lock)
@@ -107,6 +210,15 @@ public class CharArrayWriter extends Writer
       }
   }
 
+  /**
+   * This method writes <code>len</code> chars from the passed in
+   * <code>String</code> <code>buf</code> starting at index
+   * <code>offset</code> into the internal buffer.
+   *
+   * @param str The <code>String</code> to write data from
+   * @param offset The index into the string to start writing data from
+   * @param len The number of chars to write
+   */
   public void write (String str, int offset, int len) throws IOException
   {
     synchronized (lock)
@@ -121,6 +233,14 @@ public class CharArrayWriter extends Writer
       }
   }
 
+  /**
+   * This method writes all the chars that have been written to this stream
+   * from the internal buffer to the specified <code>Writer</code>.
+   *
+   * @param out The <code>Writer</code> to write to
+   *
+   * @exception IOException If an error occurs
+   */
   public void writeTo (Writer out) throws IOException
   {
     synchronized (lock)
@@ -129,6 +249,13 @@ public class CharArrayWriter extends Writer
       }
   }
 
+  /**
+   * This private method makes the buffer bigger when we run out of room
+   * by allocating a larger buffer and copying the valid chars from the
+   * old array into it.  This is obviously slow and should be avoided by
+   * application programmers by setting their initial buffer size big
+   * enough to hold everything if possible.
+   */
   private final void resize (int len)
   {
     if (count + len >= buf.length)
@@ -142,10 +269,18 @@ public class CharArrayWriter extends Writer
       }
   }
 
-  // The character buffer.
+  /**
+   * The internal buffer where the data written is stored
+   */
   protected char[] buf;
-  // Number of valid characters in buffer.
+
+  /**
+   * The number of chars that have been written to the buffer
+   */
   protected int count;
-  // True if stream is closed.
+
+  /**
+   * True if the stream has been closed.
+   */
   private boolean closed;
 }
diff --git a/libjava/java/io/InputStream.java b/libjava/java/io/InputStream.java
index 2da52b1afcd..0cf1f4322b2 100644
--- a/libjava/java/io/InputStream.java
+++ b/libjava/java/io/InputStream.java
@@ -1,56 +1,185 @@
-/* Copyright (C) 1998, 1999  Free Software Foundation
+/* InputStream.java -- Base class for input
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
-   This file is part of libgcj.
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+ 
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
  
 package java.io;
 
 /**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date October 2, 1998.  
- */
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
- 
+  * This abstract class forms the base of the hierarchy of classes that read
+  * input as a stream of bytes.  It provides a common set of methods for
+  * reading bytes from streams.  Subclasses implement and extend these
+  * methods to read bytes from a particular input source such as a file
+  * or network connection.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Warren Levy <warrenl@cygnus.com>
+  */
 public abstract class InputStream
 {
+  /**
+   * Default, no-arg, public constructor
+   */
   public InputStream()
   {
   }
 
+  /**
+   * This method returns the number of bytes that can be read from this
+   * stream before a read can block.  A return of 0 indicates that blocking
+   * might (or might not) occur on the very next read attempt.
+   * <p>
+   * This method always returns 0 in this class
+   *
+   * @return The number of bytes that can be read before blocking could occur
+   *
+   * @exception IOException If an error occurs
+   */
   public int available() throws IOException
   {
     return 0;
   }
 
+  /**
+   * This method closes the stream.  Any futher attempts to read from the
+   * stream may generate an <code>IOException</code>
+   * <p>
+   * This method does nothing in this class, but subclasses may override
+   * this method in order to provide additional functionality.
+   *
+   * @exception IOException If an error occurs, which can only happen
+   * in a subclass
+   */
   public void close() throws IOException
   {
     // Do nothing
   }
 
+  /**
+   * This method marks a position in the input to which the stream can
+   * be "reset" by calling the <code>reset()</code> method.  The
+   * parameter @code{readlimit} is the number of bytes that can be read
+   * from the stream after setting the mark before the mark becomes
+   * invalid.  For example, if <code>mark()</code> is called with a
+   * read limit of 10, then when 11 bytes of data are read from the
+   * stream before the <code>reset()</code> method is called, then the
+   * mark is invalid and the stream object instance is not required to
+   * remember the mark.
+   * <p>
+   * This method does nothing in this class, but subclasses may override it
+   * to provide mark/reset functionality.
+   *
+   * @param readLimit The number of bytes that can be read before the
+   *                  mark becomes invalid
+   */
   public void mark(int readlimit)
   {
     // Do nothing
   }
 
+  /**
+   * This method returns a boolean that indicates whether the mark/reset
+   * methods are supported in this class.  Those methods can be used to
+   * remember a specific point in the stream and reset the stream to that
+   * point.
+   * <p>
+   * This method always returns <code>false</code> in this class, but
+   * subclasses can override this method to return </code>true</code>
+   * if they support mark/reset functionality.
+   *
+   * @return <code>true</code> if mark/reset functionality is
+   * supported, <code>false</code> otherwise 
+   */
   public boolean markSupported()
   {
     return false;
   }
 
+  /**
+   * This method reads an unsigned byte from the input stream and returns it
+   * as an int in the range of 0-255.  This method also will return -1 if
+   * the end of the stream has been reached.
+   * <p>
+   * This method will block until the byte can be read.
+   *
+   * @return The byte read or -1 if end of stream
+   *
+   * @exception IOException If an error occurs
+   */
   public abstract int read() throws IOException;
 
+  /**
+   * This method reads bytes from a stream and stores them into a caller
+   * supplied buffer.  This method attempts to completely fill the buffer,
+   * but can return before doing so.  The actual number of bytes read is
+   * returned as an int.  A -1 is returned to indicate the end of the stream.
+   * <p>
+   * This method will block until some data can be read.
+   * <p>
+   * This method operates by calling an overloaded read method like so:
+   * <code>read(b, 0, b.length)</code>
+   *
+   * @param b The buffer into which the bytes read will be stored.
+   *
+   * @return The number of bytes read or -1 if end of stream.
+   *
+   * @exception IOException If an error occurs.
+   */
   public int read(byte[] b) throws IOException
   {
     return read(b, 0, b.length);
   }
 
+  /**
+   * This method read bytes from a stream and stores them into a
+   * caller supplied buffer.  It starts storing the data at index
+   * <code>off</code> into the buffer and attempts to read
+   * <code>len</code> bytes.  This method can return before reading the
+   * number of bytes requested.  The actual number of bytes read is
+   * returned as an int.  A -1 is returned to indicate the end of the
+   * stream.
+   *  <p>
+   * This method will block until some data can be read.
+   * <p>
+   * This method operates by calling the single byte <code>read()</code> method
+   * in a loop until the desired number of bytes are read.  The read loop
+   * stops short if the end of the stream is encountered or if an IOException
+   * is encountered on any read operation except the first.  If the first
+   * attempt to read a bytes fails, the IOException is allowed to propagate
+   * upward.  And subsequent IOException is caught and treated identically
+   * to an end of stream condition.  Subclasses can (and should if possible)
+   * override this method to provide a more efficient implementation.
+   *
+   * @param b The array into which the bytes read should be stored
+   * @param off The offset into the array to start storing bytes
+   * @param len The requested number of bytes to read
+   *
+   * @return The actual number of bytes read, or -1 if end of stream.
+   *
+   * @exception IOException If an error occurs.
+   */
   public int read(byte[] b, int off, int len) throws IOException
   {
     if (off < 0 || len < 0 || off + len > b.length)
@@ -62,27 +191,55 @@ public abstract class InputStream
 
     for (i = 0; i < len; ++i)
       try
-      {
-        if ((ch = read()) < 0)
-	  return i == 0 ? -1 : i;		// EOF
-        b[off + i] = (byte) ch;
-      }
+	{
+	  if ((ch = read()) < 0)
+	    return i == 0 ? -1 : i;		// EOF
+	  b[off + i] = (byte) ch;
+	}
       catch (IOException ex)
-      {
-        // Only reading the first byte should cause an IOException.
-	if (i == 0)
-	  throw ex;
-	return i;
-      }
+	{
+	  // Only reading the first byte should cause an IOException.
+	  if (i == 0)
+	    throw ex;
+	  return i;
+	}
 
     return i;
   }
 
+  /**
+   * This method resets a stream to the point where the
+   * <code>mark()</code> method was called.  Any bytes that were read
+   * after the mark point was set will be re-read during subsequent
+   * reads.
+   * <p>
+   * This method always throws an IOException in this class, but subclasses
+   * can override this method if they provide mark/reset functionality.
+   *
+   * @exception IOException Always thrown for this class
+   */
   public void reset() throws IOException
   {
     throw new IOException("mark/reset not supported");
   }
 
+  /**
+   * This method skips the specified number of bytes in the stream.  It
+   * returns the actual number of bytes skipped, which may be less than the
+   * requested amount.
+   * <p>
+   * This method reads and discards bytes into a byte array until the
+   * specified number of bytes were skipped or until either the end of stream
+   * is reached or a read attempt returns a short count.  Subclasses can
+   * override this metho to provide a more efficient implementation where
+   * one exists.
+   *
+   * @param n The requested number of bytes to skip
+   *
+   * @return The actual number of bytes skipped.
+   *
+   * @exception IOException If an error occurs
+   */
   public long skip(long n) throws IOException
   {
     // Throw away n bytes by reading them into a temp byte[].
diff --git a/libjava/java/io/OutputStream.java b/libjava/java/io/OutputStream.java
index 46770394b22..d4d9a190cff 100644
--- a/libjava/java/io/OutputStream.java
+++ b/libjava/java/io/OutputStream.java
@@ -1,34 +1,95 @@
-// OutputStream.java - Send output bytes to output sink.
+/* OutputStream.java -- Base class for byte output streams
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
-/* Copyright (C) 1998, 1999  Free Software Foundation
+This file is part of GNU Classpath.
 
-   This file is part of libgcj.
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+ 
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
 
-package java.io;
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
 
-/**
- * @author Tom Tromey <tromey@cygnus.com>
- * @date September 24, 1998 
- */
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * Status:  Complete to version 1.1.
- */
+package java.io;
 
+/**
+  * This abstract class forms the base of the hierarchy of classes that 
+  * write output as a stream of bytes.  It provides a common set of methods
+  * for writing bytes to stream.  Subclasses implement and/or extend these
+  * methods to write bytes in a particular manner or to a particular 
+  * destination such as a file on disk or network connection.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Tom Tromey <tromey@cygnus.com>
+  */
 public abstract class OutputStream
 {
+  /**
+   * This is the default no-argument constructor for this class.  This method
+   * does nothing in this class.
+   */
+  public OutputStream ()
+  {
+  }
+
+  /**
+   * This method writes a single byte to the output stream.  The byte written
+   * is the low eight bits of the <code>int</code> passed and a argument.
+   * <p>
+   * Subclasses must provide an implementation of this abstract method
+   *
+   * @param b The byte to be written to the output stream, passed as
+   *          the low eight bits of an <code>int</code> 
+   *
+   * @exception IOException If an error occurs
+   */
   public abstract void write (int b) throws IOException;
 
+  /**
+   * This method all the writes bytes from the passed array to the
+   * output stream.  This method is equivalent to <code>write(b, 0,
+   * buf.length)</code> which is exactly how it is implemented in this
+   * class.
+   *
+   * @param b The array of bytes to write
+   *
+   * @exception IOException If an error occurs
+   */
   public void write (byte[] b) throws IOException, NullPointerException
   {
     write (b, 0, b.length);
   }
 
+  /**
+   * This method writes <code>len</code> bytes from the specified array
+   * <code>b</code> starting at index <code>off</code> into the array.
+   * <p>
+   * This method in this class calls the single byte <code>write()</code>
+   * method in a loop until all bytes have been written.  Subclasses should
+   * override this method if possible in order to provide a more efficent
+   * implementation.
+   *
+   * @param b The array of bytes to write from
+   * @param off The index into the array to start writing from
+   * @param len The number of bytes to write
+   * 
+   * @exception IOException If an error occurs
+   */
   public void write (byte[] b, int off, int len)
     throws IOException, NullPointerException, IndexOutOfBoundsException
   {
@@ -38,10 +99,30 @@ public abstract class OutputStream
       write (b[off + i]);
   }
 
+  /**
+   * This method forces any data that may have been buffered to be written
+   * to the underlying output device.  Please note that the host environment
+   * might perform its own buffering unbeknowst to Java.  In that case, a
+   * write made (for example, to a disk drive) might be cached in OS
+   * buffers instead of actually being written to disk.
+   * <p>
+   * This method in this class does nothing.
+   *
+   * @exception IOException If an error occurs
+   */
   public void flush () throws IOException
   {
   }
 
+  /**
+   * This method closes the stream.  Any internal or native resources
+   * associated with this stream are freed.  Any subsequent attempt to
+   * access the stream might throw an exception.
+   * <p>
+   * This method in this class does nothing.
+   *
+   * @exception IOException If an error occurs
+   */
   public void close () throws IOException
   {
   }
diff --git a/libjava/java/io/PushbackInputStream.java b/libjava/java/io/PushbackInputStream.java
index 537e1dbec57..94c83ab742f 100644
--- a/libjava/java/io/PushbackInputStream.java
+++ b/libjava/java/io/PushbackInputStream.java
@@ -1,36 +1,86 @@
-/* Copyright (C) 1998, 1999, 2000  Free Software Foundation
+/* PushbackInputStream.java -- An input stream that can unread bytes
+   Copyright (C) 1998, 1999, 2001, 2001 Free Software Foundation, Inc.
 
-   This file is part of libgcj.
+This file is part of GNU Classpath.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
  
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
+
 package java.io;
 
 /**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date October 15, 1998.  
- */
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
- 
+  * This subclass of <code>FilterInputStream</code> provides the ability to 
+  * unread data from a stream.  It maintains an internal buffer of unread
+  * data that is supplied to the next read operation.  This is conceptually
+  * similar to mark/reset functionality, except that in this case the 
+  * position to reset the stream to does not need to be known in advance.
+  * <p>
+  * The default pushback buffer size one byte, but this can be overridden
+  * by the creator of the stream.
+  * <p>
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Warren Levy <warrenl@cygnus.com>
+  */
 public class PushbackInputStream extends FilterInputStream
 {
-  /* Internal buffer array for data. */
+  /**
+   * This is the default buffer size
+   */
+  private static final int DEFAULT_BUFFER_SIZE = 1;
+
+  /**
+   * This is the buffer that is used to store the pushed back data
+   */
   protected byte[] buf;
 
-  /* The current position in the buffer. */
+  /**
+   * This is the position in the buffer from which the next byte will be
+   * read.  Bytes are stored in reverse order in the buffer, starting from
+   * <code>buf[buf.length - 1]</code> to <code>buf[0]</code>.  Thus when 
+   * <code>pos</code> is 0 the buffer is full and <code>buf.length</code> when 
+   * it is empty
+   */
   protected int pos;
 
+  /**
+   * This method initializes a <code>PushbackInputStream</code> to
+   * read from the * specified subordinate <code>InputStream</code>
+   * with a default pushback buffer * size of 1.
+   *
+   * @param in The subordinate stream to read from
+   */
   public PushbackInputStream(InputStream in)
   {
-    this(in, 1);
+    this(in, DEFAULT_BUFFER_SIZE);
   }
 
+  /**
+   * This method initializes a <code>PushbackInputStream</code> to
+   * read from the specified subordinate <code>InputStream</code> with
+   * the specified buffer size
+   *
+   * @param in The subordinate <code>InputStream</code> to read from
+   * @param size The pushback buffer size to use
+   */
   public PushbackInputStream(InputStream in, int size)
   {
     super(in);
@@ -40,23 +90,72 @@ public class PushbackInputStream extends FilterInputStream
     pos = buf.length;
   }
 
+  /**
+   * This method returns the number of bytes that can be read from this
+   * stream before a read can block.  A return of 0 indicates that blocking
+   * might (or might not) occur on the very next read attempt.
+   * <p>
+   * This method will return the number of bytes available from the
+   * pushback buffer plus the number of bytes available from the 
+   * underlying stream.
+   *
+   * @return The number of bytes that can be read before blocking could occur
+   *
+   * @exception IOException If an error occurs
+   */
   public int available() throws IOException
   {
     return pos + super.available();
   }
 
-  public void close() throws IOException
+  /**
+   * This method closes the stream and releases any associated resources.
+   * 
+   * @exception IOException If an error occurs.
+   */
+  public synchronized void close() throws IOException
   {
     buf = null;
     super.close();
   }
 
+  /**
+   * This method returns <code>false</code> to indicate that it does
+   * not support mark/reset functionality.
+   *
+   * @return This method returns <code>false</code> to indicate that
+   * this class does not support mark/reset functionality
+   */
   public boolean markSupported()
   {
     return false;
   }
 
-  public int read() throws IOException
+  /**
+   * This method always throws an IOException in this class because
+   * mark/reset functionality is not supported.
+   *
+   * @exception IOException Always thrown for this class
+   */
+  public void reset() throws IOException
+  {
+    throw new IOException("Mark not supported in this class");
+  }
+
+  /**
+   * This method reads an unsigned byte from the input stream and returns it
+   * as an int in the range of 0-255.  This method also will return -1 if
+   * the end of the stream has been reached.  The byte returned will be read
+   * from the pushback buffer, unless the buffer is empty, in which case
+   * the byte will be read from the underlying stream.
+   * <p>
+   * This method will block until the byte can be read.
+   *
+   * @return The byte read or -1 if end of stream
+   *
+   * @exception IOException If an error occurs
+   */
+  public synchronized int read() throws IOException
   {
     if (pos < buf.length)
       return ((int) buf[pos++]) & 0xFF;
@@ -64,7 +163,31 @@ public class PushbackInputStream extends FilterInputStream
     return super.read();
   }
 
-  public int read(byte[] b, int off, int len) throws IOException
+  /**
+   * This method read bytes from a stream and stores them into a
+   * caller supplied buffer.  It starts storing the data at index
+   * <code>offset</code> into the buffer and attempts to read
+   * <code>len</code> bytes.  This method can return before reading the
+   * number of bytes requested.  The actual number of bytes read is
+   * returned as an int.  A -1 is returned to indicate the end of the
+   * stream.
+   *  <p>
+   * This method will block until some data can be read.
+   * <p>
+   * This method first reads bytes from the pushback buffer in order to 
+   * satisfy the read request.  If the pushback buffer cannot provide all
+   * of the bytes requested, the remaining bytes are read from the 
+   * underlying stream.
+   *
+   * @param b The array into which the bytes read should be stored
+   * @param off The offset into the array to start storing bytes
+   * @param len The requested number of bytes to read
+   *
+   * @return The actual number of bytes read, or -1 if end of stream.
+   *
+   * @exception IOException If an error occurs.
+   */
+  public synchronized int read(byte[] b, int off, int len) throws IOException
   {
     if (off < 0 || len < 0 || off + len > b.length)
       throw new ArrayIndexOutOfBoundsException();
@@ -80,23 +203,68 @@ public class PushbackInputStream extends FilterInputStream
     return super.read(b, off, len);
   }
 
-  public void unread(int b) throws IOException
+  /**
+   * This method pushes a single byte of data into the pushback buffer.
+   * The byte pushed back is the one that will be returned as the first byte
+   * of the next read.
+   * <p>
+   * If the pushback buffer is full, this method throws an exception.
+   * <p>
+   * The argument to this method is an <code>int</code>.  Only the low
+   * eight bits of this value are pushed back.
+   *
+   * @param b The byte to be pushed back, passed as an int
+   *
+   * @exception IOException If the pushback buffer is full.
+   */
+  public synchronized void unread(int b) throws IOException
   {
     if (pos <= 0)
-      throw new IOException();
+      throw new IOException("Insufficient space in pushback buffer");
 
     buf[--pos] = (byte) b;
   }
 
-  public void unread(byte[] b) throws IOException
+  /**
+   * This method pushes all of the bytes in the passed byte array into 
+   * the pushback bfer.  These bytes are pushed in reverse order so that
+   * the next byte read from the stream after this operation will be
+   * <code>b[0]</code> followed by <code>b[1]</code>, etc.
+   * <p>
+   * If the pushback buffer cannot hold all of the requested bytes, an
+   * exception is thrown.
+   *
+   * @param b The byte array to be pushed back
+   *
+   * @exception IOException If the pushback buffer is full
+   */
+  public synchronized void unread(byte[] b) throws IOException
   {
     unread(b, 0, b.length);
   }
 
-  public void unread(byte[] b, int off, int len) throws IOException
+  /**
+   * This method pushed back bytes from the passed in array into the
+   * pushback buffer.  The bytes from <code>b[offset]</code> to
+   * <cdoe>b[offset + len]</code> are pushed in reverse order so that
+   * the next byte read from the stream after this operation will be
+   * <code>b[offset]</code> followed by <code>b[offset + 1]</code>,
+   * etc.
+   * <p>
+   * If the pushback buffer cannot hold all of the requested bytes, an
+   * exception is thrown.
+   *
+   * @param b The byte array to be pushed back
+   * @param off The index into the array where the bytes to be push start
+   * @param len The number of bytes to be pushed.
+   *
+   * @exception IOException If the pushback buffer is full
+   */
+  public synchronized void unread(byte[] b, int off, int len)
+    throws IOException
   {
     if (pos < len)
-      throw new IOException();
+      throw new IOException("Insufficient space in pushback buffer");
 
     // Note the order that these bytes are being added is the opposite
     // of what would be done if they were added to the buffer one at a time.
@@ -108,8 +276,24 @@ public class PushbackInputStream extends FilterInputStream
     pos -= len;
   }
 
-  // JDK1.2
-  public long skip(long n) throws IOException
+  /**
+   * This method skips the specified number of bytes in the stream.  It
+   * returns the actual number of bytes skipped, which may be less than the
+   * requested amount.
+   * <p>
+   * This method first discards bytes from the buffer, then calls the
+   * <code>skip</code> method on the underlying <code>InputStream</code> to 
+   * skip additional bytes if necessary.
+   *
+   * @param num_bytes The requested number of bytes to skip
+   *
+   * @return The actual number of bytes skipped.
+   *
+   * @exception IOException If an error occurs
+   *
+   * @since 1.2
+   */
+  public synchronized long skip(long n) throws IOException
   {
     final long origN = n;
 
diff --git a/libjava/java/io/StringWriter.java b/libjava/java/io/StringWriter.java
index 92135437983..10cc3ec307f 100644
--- a/libjava/java/io/StringWriter.java
+++ b/libjava/java/io/StringWriter.java
@@ -1,27 +1,55 @@
-// StringWriter.java - StringBuffer output stream
+/* StringWriter.java -- Writes bytes to a StringBuffer
+   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
 
-/* Copyright (C) 1998, 1999, 2000  Free Software Foundation
+This file is part of GNU Classpath.
 
-   This file is part of libgcj.
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+ 
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
 
-package java.io;
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
 
-/**
- * @author Tom Tromey <tromey@cygnus.com>
- * @date September 25, 1998 
- */
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * Status:  Complete to 1.2.
- */
+package java.io;
 
+// Wow is this a dumb class.  CharArrayWriter can do all this and
+// more.  I would redirect all calls to one in fact, but the javadocs say
+// use a StringBuffer so I will comply.
+
+/**
+  * This class writes chars to an internal <code>StringBuffer</code> that
+  * can then be used to retrieve a <code>String</code>.
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Tom Tromey <tromey@cygnus.com>
+  */
 public class StringWriter extends Writer
 {
+  /**
+   * This is the default size of the buffer if the user doesn't specify it.
+   * @specnote The JCL Volume 1 says that 16 is the default size.
+   */
+  private static final int DEFAULT_BUFFER_SIZE = 16;
+
+  /**
+   * This method closes the stream.  The contents of the internal buffer
+   * can still be retrieved, but future writes are not guaranteed to work.
+   */
   public void close ()
   {
     // JCL says this does nothing.  This seems to violate the Writer
@@ -29,20 +57,42 @@ public class StringWriter extends Writer
     // IOException after a close.  Still, we just follow JCL.
   }
 
+  /**
+   * This method flushes any buffered characters to the underlying output.
+   * It does nothing in this class.
+   */
   public void flush ()
   {
   }
 
+  /**
+   * This method returns the <code>StringBuffer</code> object that this
+   * object is writing to.  Note that this is the actual internal buffer, so
+   * any operations performed on it will affect this stream object.
+   *
+   * @return The <code>StringBuffer</code> object being written to
+   */
   public StringBuffer getBuffer ()
   {
     return buffer;
   }
 
+  /**
+   * This method initializes a new <code>StringWriter</code> to write to a
+   * <code>StringBuffer</code> initially sized to a default size of 16
+   * chars.
+   */
   public StringWriter ()
   {
-    this (16);
+    this (DEFAULT_BUFFER_SIZE);
   }
 
+  /**
+   * This method initializes a new <code>StringWriter</code> to write to a
+   * <code>StringBuffer</code> with the specified initial size.
+   *
+   * @param size The initial size to make the <code>StringBuffer</code>
+   */
   public StringWriter (int size)
   {
     super ();
@@ -50,31 +100,79 @@ public class StringWriter extends Writer
     lock = buffer;
   }
 
+  /**
+   * This method returns the contents of the internal <code>StringBuffer</code>
+   * as a <code>String</code>.
+   *
+   * @return A <code>String</code> representing the chars written to
+   * this stream. 
+   */
   public String toString ()
   {
     return buffer.toString();
   }
 
+  /**
+   * This method writes a single character to the output, storing it in
+   * the internal buffer.
+   *
+   * @param oneChar The <code>char</code> to write, passed as an int.
+   */
   public void write (int oneChar)
   {
-    buffer.append((char) oneChar);
+    buffer.append((char) (oneChar & 0xFFFF));
   }
 
+  /**
+   * This method writes <code>len</code> chars from the specified
+   * array starting at index <code>offset</code> in that array to this
+   * stream by appending the chars to the end of the internal buffer.
+   *
+   * @param chars The array of chars to write
+   * @param offset The index into the array to start writing from
+   * @param len The number of chars to write
+   */
   public void write (char[] chars, int offset, int len)
   {
     buffer.append(chars, offset, len);
   }
 
+  /**
+   * This method writes the characters in the specified <code>String</code>
+   * to the stream by appending them to the end of the internal buffer.
+   *
+   * @param str The <code>String</code> to write to the stream.
+   */
   public void write (String str)
   {
     buffer.append(str);
   }
 
+  /**
+   * This method writes out <code>len</code> characters of the specified
+   * <code>String</code> to the stream starting at character position
+   * <code>offset</code> into the stream.  This is done by appending the
+   * characters to the internal buffer.
+   *
+   * @param str The <code>String</code> to write characters from
+   * @param offset The character position to start writing from
+   * @param len The number of characters to write.
+   */ 
   public void write (String str, int offset, int len)
   {
+//      char[] tmpbuf = new char[len];
+//      str.getChars(offset, offset+len, tmpbuf, 0);
+//      buf.append(tmpbuf, 0, tmpbuf.length);
+    // This implementation assumes that String.substring is more
+    // efficient than using String.getChars and copying the data
+    // twice.  For libgcj, this is true.  For Classpath, it is not.
+    // FIXME.
     buffer.append(str.substring(offset, offset + len));
   }
 
-  // The string buffer.
+  /**
+   * This is the <code>StringBuffer</code> that we use to store bytes that
+   * are written.
+   */
   private StringBuffer buffer;
 }