1 files changed, 106 insertions, 11 deletions

diff --git a/libjava/java/io/BufferedWriter.java b/libjava/java/io/BufferedWriter.java
index 3112a8a..f31dc28 100644
--- a/libjava/java/io/BufferedWriter.java
+++ b/libjava/java/io/BufferedWriter.java
@@ -1,6 +1,6 @@
 // BufferedWriter.java - Filtered character output stream.
 
-/* Copyright (C) 1998, 1999  Free Software Foundation
+/* Copyright (C) 1998, 1999, 2000  Free Software Foundation
 
    This file is part of libgcj.
 
@@ -10,24 +10,48 @@ details.  */
 
 package java.io;
 
-/**
- * @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 version 1.1.
  */
 
-// Why not extend FilterWriter?
+/**
+  * This class accumulates chars written in a buffer instead of immediately
+  * writing the data to the underlying output sink. The chars are instead
+  * as one large block when the buffer is filled, or when the stream is
+  * closed or explicitly flushed. This mode operation can provide a more
+  * efficient mechanism for writing versus doing numerous small unbuffered
+  * writes.
+  *
+  * @version 0.0
+  *
+  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Tom Tromey <tromey@cygnus.com>
+  * @date September 25, 1998 
+  */
+
 public class BufferedWriter extends Writer
 {
+  /**
+   * This method initializes a new <code>BufferedWriter</code> instance
+   * that will write to the specified subordinate <code>Writer</code>
+   * and which will use a default buffer size of 512 chars.
+   *
+   * @param out The underlying <code>Writer</code> to write data to
+   */
   public BufferedWriter (Writer out)
   {
-    this (out, 8192);
+    this (out, DEFAULT_BUFFER_SIZE);
   }
 
+  /**
+   * This method initializes a new <code>BufferedWriter</code> instance
+   * that will write to the specified subordinate <code>Writer</code>
+   * and which will use the specified buffer size
+   *
+   * @param out The underlying <code>Writer</code> to write data to
+   * @param size The size of the internal buffer
+   */
   public BufferedWriter (Writer ox, int size)
   {
     super (ox);
@@ -36,23 +60,51 @@ public class BufferedWriter extends Writer
     count = 0;
   }
 
+  /**
+   * This method flushes any remaining buffered chars then closes the 
+   * underlying output stream.  Any further attempts to write to this stream
+   * may throw an exception
+   */
   public void close () throws IOException
   {
     localFlush ();
     out.close();
   }
 
+  /**
+   * This method causes any currently buffered chars to be immediately
+   * written to the underlying output stream.
+   *
+   * @exception IOException If an error occurs
+   */
   public void flush () throws IOException
   {
     localFlush ();
     out.flush();
   }
 
+  /**
+   * This method writes out a system depedent line separator sequence.  The
+   * actual value written is detemined from the <xmp>line.separator</xmp>
+   * system property.
+   *
+   * @exception IOException If an error occurs
+   */
   public void newLine () throws IOException
   {
     write (System.getProperty("line.separator"));
   }
 
+  /**
+   * This method writes a single char of data.  This will be written to the
+   * buffer instead of the underlying data source.  However, if the buffer
+   * is filled as a result of this write request, it will be flushed to the
+   * underlying output stream.
+   *
+   * @param b The char of data to be written, passed as an int
+   *
+   * @exception IOException If an error occurs
+   */
   public void write (int oneChar) throws IOException
   {
     synchronized (lock)
@@ -63,6 +115,19 @@ public class BufferedWriter extends Writer
       }
   }
 
+  /**
+   * This method writes <code>len</code> chars from the char array 
+   * <code>buf</code> starting at position <code>offset</code> in the buffer. 
+   * These chars will be written to the internal buffer.  However, if this
+   * write operation fills the buffer, the buffer will be flushed to the
+   * underlying output stream.
+   *
+   * @param buf The array of chars to write.
+   * @param offset The index into the char array to start writing from.
+   * @param len The number of chars to write.
+   *
+   * @exception IOException If an error occurs
+   */
   public void write (char[] buf, int offset, int len) throws IOException
   {
     if (offset < 0 || len < 0 || offset + len > buf.length)
@@ -86,6 +151,19 @@ public class BufferedWriter extends Writer
       }
   }
 
+  /**
+   * This method writes <code>len</code> chars from the <code>String</code>
+   * <code>str</code> starting at position <code>offset</code> in the string. 
+   * These chars will be written to the internal buffer.  However, if this
+   * write operation fills the buffer, the buffer will be flushed to the
+   * underlying output stream.
+   *
+   * @param str The <code>String</code> to write.
+   * @param offset The index into the string to start writing from.
+   * @param len The number of chars to write.
+   *
+   * @exception IOException If an error occurs
+   */
   public void write (String str, int offset, int len) throws IOException
   {
     if (offset < 0 || len < 0 || offset + len < str.length())
@@ -120,10 +198,27 @@ public class BufferedWriter extends Writer
       }
   }
 
-  // The downstream writer.
+  /**
+   * This is the underlying <code>Writer</code> to which this object
+   * sends its output.
+   */
   private Writer out;
-  // The character buffer.
+
+  /**
+   * This is the internal char array used for buffering output before
+   * writing it.
+   */
   char[] buffer;
-  // Number of valid chars in buffer.
+
+  /**
+   * This is the number of chars that are currently in the buffer and
+   * are waiting to be written to the underlying stream.  It always points to
+   * the index into the buffer where the next char of data will be stored
+   */
   int count;
+
+  /**
+   * This is the default buffer size
+   */
+  private static final int DEFAULT_BUFFER_SIZE = 8192;
 }