2003-05-06 Michael Koch <konqueror@gmx.de>

	* java/io/DataOutputStream.java
	(write): Renamed argument to "value", merged documentation from
	classpath.
	(writeBoolean): Likewise.
	(writeByte): Likewise.
	(writeShort): Likewise.
	(writeChar): Likewise.
	(writeInt): Likewise.
	(writeLong): Likewise.
	(writeFloat): Likewise.
	(writeDouble): Likewise.
	(writeBytes): Likewise.
	(writeChars): Likewise.
	(writeUTF): Likewise.
	* java/io/File.java
	(performDelete): Added documentation.
	(performList): Likewise.
	(performMkdir): Likewise.
	(performSetReadOnly): Likewise.
	(performRenameTo): Likewise.
	(performSetLastModified): Likewise.
	(delete): Made it sychronized.
	(renameTo): Made it sychronized.
	(equals): Reformatted.
	(isHidden): Likewise.
	(listFiles): Likewise.
	(setReadOnly): Likewise.
	(listRoots): Likewise.
	(setLastModified): Likewise.
	(checkRead): Likewise.
	(checkWrite): Likewise.
	* java/io/FileInputStream.java
	(skip): Made it sychronized, merged from classpath.
	* java/io/FileOutputStream.java
	(write): Merged from classpath.
	* java/io/InputStreamReader.java:
	(InputStreamReader): Merged documentation from classpath.

From-SVN: r66520

5 files changed, 264 insertions, 98 deletions

diff --git a/libjava/java/io/DataOutputStream.java b/libjava/java/io/DataOutputStream.java
index 644b590..d5f76ff 100644
--- a/libjava/java/io/DataOutputStream.java
+++ b/libjava/java/io/DataOutputStream.java
@@ -101,13 +101,13 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput
    * This method writes the specified byte (passed as an <code>int</code>)
    * to the underlying output stream.
    *
-   * @param b The byte to write, passed as an <code>int</code>.
+   * @param value The <code>byte</code> to write, passed as an <code>int</code>.
    *
    * @exception IOException If an error occurs.
    */
-  public synchronized void write (int b) throws IOException
+  public synchronized void write (int value) throws IOException
   {
-    out.write(b);
+    out.write (value);
     ++written;
   }
 
@@ -130,116 +130,185 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput
   }
 
   /**
-   * This method writes a Java <code>boolean</code> to the underlying output 
-   * stream. For a value of <code>true</code>, 1 is written to the stream.
-   * For a value of <code>false</code>, 0 is written.
+   * 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.
    *
-   * @param b The <code>boolean</code> value to write to the stream
+   * The value written can be read using the <code>readBoolean</code>
+   * method in <code>DataInput</code>.
+   *
+   * @param value The <code>boolean</code> value to write to the stream
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readBoolean
    */
-  public final void writeBoolean (boolean v) throws IOException
+  public final void writeBoolean (boolean value) throws IOException
   {
-    write (v ? 1 : 0);
+    write (value ? 1 : 0);
   }
 
   /**
-   * This method writes a Java <code>byte</code> value to the underlying
-   * 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 b The <code>byte</code> to write to the stream, passed as 
+   * @param value The <code>byte</code> to write to the stream, passed as 
    * the low eight bits of an <code>int</code>.
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readByte
+   * @see DataInput#readUnsignedByte
    */
-  public final void writeByte (int v) throws IOException
+  public final void writeByte (int value) throws IOException
   {
-    write (v & 0xff);
+    write (value & 0xff);
   }
 
   /**
-   * This method writes a Java <code>short</code> to the stream, high byte
-   * first.  This method requires two bytes to encode the value.
+   * This method writes a Java short 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 s The <code>short</code> value to write to the stream,
+   * @param value The <code>short</code> value to write to the stream,
    * passed as an <code>int</code>.
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readShort
+   * @see DataInput#readUnsignedShort
    */
-  public final void writeShort (int v) throws IOException
+  public final void writeShort (int value) throws IOException
   {
-    write ((byte) (0xff & (v >> 8)));
-    write ((byte) (0xff & v));
+    write ((byte) (0xff & (value >> 8)));
+    write ((byte) (0xff & value));
   }
 
   /**
-   * This method writes a single <code>char</code> value to the stream,
-   * high byte first.
+   * 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 c The <code>char</code> value to write, 
+   * @param value The <code>char</code> value to write, 
    * passed as an <code>int</code>.
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readChar
    */
-  public final void writeChar (int v) throws IOException
+  public final void writeChar (int value) throws IOException
   {
-    write ((byte) (0xff & (v >> 8)));
-    write ((byte) (0xff & v));
+    write ((byte) (0xff & (value >> 8)));
+    write ((byte) (0xff & value));
   }
 
   /**
-   * This method writes a Java <code>int</code> to the stream, high bytes
-   * first.  This method requires four bytes to encode the value.
+   * 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>
    *
-   * @param i The <code>int</code> value to write to the stream.
+   * The value written can be read using the <code>readInt</code>
+   * method in <code>DataInput</code>.
+   *
+   * @param value The <code>int</code> value to write to the stream
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readInt
    */
-  public final void writeInt (int v) throws IOException
+  public final void writeInt (int value) throws IOException
   {
-    write ((byte) (0xff & (v >> 24)));
-    write ((byte) (0xff & (v >> 16)));
-    write ((byte) (0xff & (v >>  8)));
-    write ((byte) (0xff & v));
+    write ((byte) (0xff & (value >> 24)));
+    write ((byte) (0xff & (value >> 16)));
+    write ((byte) (0xff & (value >>  8)));
+    write ((byte) (0xff & value));
   }
 
   /**
-   * This method writes a Java <code>long</code> to the stream, high bytes
-   * first.  This method requires eight bytes to encode the value.
+   * 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>
    *
-   * @param l The <code>long</code> value to write to the stream.
+   * The value written can be read using the <code>readLong</code>
+   * method in <code>DataInput</code>.
+   *
+   * @param value The <code>long</code> value to write to the stream
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readLong
    */
-  public final void writeLong (long v) throws IOException
+  public final void writeLong (long value) throws IOException
   {
-    write ((byte) (0xff & (v >> 56)));
-    write ((byte) (0xff & (v >> 48)));
-    write ((byte) (0xff & (v >> 40)));
-    write ((byte) (0xff & (v >> 32)));
-    write ((byte) (0xff & (v >> 24)));
-    write ((byte) (0xff & (v >> 16)));
-    write ((byte) (0xff & (v >>  8)));
-    write ((byte) (0xff & v));
+    write ((byte) (0xff & (value >> 56)));
+    write ((byte) (0xff & (value>> 48)));
+    write ((byte) (0xff & (value>> 40)));
+    write ((byte) (0xff & (value>> 32)));
+    write ((byte) (0xff & (value>> 24)));
+    write ((byte) (0xff & (value>> 16)));
+    write ((byte) (0xff & (value>>  8)));
+    write ((byte) (0xff & value));
   }
 
   /**
    * This method writes a Java <code>float</code> value to the stream.  This
-   * value is written by first calling the method 
+   * 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.
    *
-   * @param f The floating point number to write to the stream.
+   * The value written can be read using the <code>readFloat</code>
+   * method in <code>DataInput</code>.
+   *
+   * @param value The <code>float</code> value to write to the stream
    *
    * @exception IOException If an error occurs
    *
    * @see writeInt
+   * @see DataInput#readFloat
+   * @see Float#floatToIntBits
    */
-  public final void writeFloat (float v) throws IOException
+  public final void writeFloat (float value) throws IOException
   {
-    writeInt (Float.floatToIntBits(v));
+    writeInt (Float.floatToIntBits (value));
   }
 
   /**
@@ -250,49 +319,57 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput
    * then writing this <code>long</code> value to the stream exactly the same
    * as the <code>writeLong()</code> method does.
    *
-   * @param d The double precision floating point number to write to 
-   * the stream.
+   * The value written can be read using the <code>readDouble</code>
+   * method in <code>DataInput</code>.
+   *
+   * @param value The <code>double</code> value to write to the stream
    *
    * @exception IOException If an error occurs
    *
    * @see writeLong
+   * @see DataInput#readDouble
+   * @see Double#doubleToLongBits
    */
-  public final void writeDouble (double v) throws IOException
+  public final void writeDouble (double value) throws IOException
   {
-    writeLong (Double.doubleToLongBits(v));
+    writeLong (Double.doubleToLongBits (value));
   }
 
   /**
    * 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.
+   * The high eight bits of each character are discarded, thus this
+   * method is inappropriate for completely representing Unicode characters.
    *
-   * @param s The <code>String</code> to write to the stream
+   * @param value The <code>String</code> to write to the stream
    *
    * @exception IOException If an error occurs
    */
-  public final void writeBytes (String s) throws IOException
+  public final void writeBytes (String value) throws IOException
   {
-    int len = s.length();
+    int len = value.length();
     for (int i = 0; i < len; ++i)
-      writeByte (s.charAt(i));
+      writeByte (value.charAt(i));
   }
 
   /**
-   * This method writes all the characters in a <code>String</code> to the
-   * stream.  There will be two bytes for each character value.  The high
-   * byte of the character will be written first.
+   * This method writes all the characters 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 s The <code>String</code> to write to the stream.
+   * @param value The <code>String</code> to write to the stream
    *
    * @exception IOException If an error occurs
+   *
+   * @see writeChar
    */
-  public final void writeChars (String s) throws IOException
+  public final void writeChars (String value) throws IOException
   {
-    int len = s.length();
+    int len = value.length();
     for (int i = 0; i < len; ++i)
-      writeChar (s.charAt(i));
+      writeChar (value.charAt(i));
   }
 
   /**
@@ -318,9 +395,14 @@ public class DataOutputStream extends FilterOutputStream implements DataOutput
    * character value are stored in bits 0-5 of byte three, with the high bits
    * of that byte set to "10".
    *
-   * @param s The <code>String</code> to write to the output in UTF format
+   * The value written can be read using the <code>readUTF</code>
+   * method in <code>DataInput</code>.
+   *
+   * @param value The <code>String</code> to write to the output in UTF format
    *
    * @exception IOException If an error occurs
+   *
+   * @see DataInput#readUTF
    */
   public final void writeUTF (String s) throws IOException
   {
diff --git a/libjava/java/io/File.java b/libjava/java/io/File.java
index 56d3a63..4872076 100644
--- a/libjava/java/io/File.java
+++ b/libjava/java/io/File.java
@@ -199,7 +199,10 @@ public class File implements Serializable, Comparable
     checkWrite();
     return performCreate();
   }
-  
+ 
+  /*
+   * This native method handles the actual deleting of the file
+   */
   private native boolean performDelete ();
 
   /**
@@ -211,12 +214,13 @@ public class File implements Serializable, Comparable
    *
    * @exception SecurityException If deleting of the file is not allowed
    */
-  public boolean delete ()
+  public synchronized boolean delete ()
   {
-    SecurityManager s = System.getSecurityManager();
-    String name = path;
+    SecurityManager s = System.getSecurityManager ();
+    
     if (s != null)
-      s.checkDelete(path);
+      s.checkDelete (path);
+    
     return performDelete ();
   }
 
@@ -239,11 +243,12 @@ public class File implements Serializable, Comparable
   {
     if (! (obj instanceof File))
       return false;
+    
     File other = (File) obj;
     if (caseSensitive)
-      return (path.equals(other.path));
+      return path.equals(other.path);
     else
-      return (path.equalsIgnoreCase(other.path));      
+      return path.equalsIgnoreCase(other.path);
   }
 
   /**
@@ -663,7 +668,7 @@ public class File implements Serializable, Comparable
    *
    * @since 1.2
    */
-  public boolean isHidden()
+  public boolean isHidden ()
   {
     checkRead();
     return _stat (ISHIDDEN);
@@ -701,6 +706,11 @@ public class File implements Serializable, Comparable
     checkRead();
     return attr (LENGTH);
   }
+
+  /*
+   * This native function actually produces the list of file in this
+   * directory
+   */
     
   private final native Object[] performList (FilenameFilter filter,
 					     FileFilter fileFilter,
@@ -781,7 +791,7 @@ public class File implements Serializable, Comparable
    *
    * @since 1.2
    */
-  public File[] listFiles()
+  public File[] listFiles ()
   {
     checkRead();
     return (File[]) performList (null, null, File.class);
@@ -811,12 +821,12 @@ public class File implements Serializable, Comparable
    *
    * @since 1.2
    */
-  public File[] listFiles(FilenameFilter filter)
+  public File[] listFiles (FilenameFilter filter)
   {
     checkRead();
     return (File[]) performList (filter, null, File.class);
   }
-  
+
   /**
    * This method returns an array of <code>File</code> objects representing
    * all the files in the directory represented by this object. If this
@@ -841,7 +851,7 @@ public class File implements Serializable, Comparable
    *
    * @since 1.2
    */
-  public File[] listFiles(FileFilter filter)
+  public File[] listFiles (FileFilter filter)
   {
     checkRead();
     return (File[]) performList (null, filter, File.class);
@@ -880,6 +890,9 @@ public class File implements Serializable, Comparable
 		      + (isDirectory() ? "/" : ""));
   }
 
+  /*
+   * This native method actually creates the directory
+   */
   private final native boolean performMkdir ();
 
   /**
@@ -1025,6 +1038,9 @@ public class File implements Serializable, Comparable
     throw new IOException ("cannot create temporary file");
   }
 
+  /*
+   * This native method sets the permissions to make the file read only.
+   */
   private native boolean performSetReadOnly();
 
   /**
@@ -1041,7 +1057,7 @@ public class File implements Serializable, Comparable
    *
    * @since 1.2
    */
-  public boolean setReadOnly()
+  public boolean setReadOnly ()
   {
     checkWrite();
     return performSetReadOnly();
@@ -1060,7 +1076,7 @@ public class File implements Serializable, Comparable
    *
    * @since 1.2
    */
-  public static File[] listRoots()
+  public static File[] listRoots ()
   {
     File[] roots = performListRoots();
     
@@ -1180,6 +1196,9 @@ public class File implements Serializable, Comparable
     return compareTo (other);
   }
 
+  /*
+   * This native method actually performs the rename.
+   */
   private native boolean performRenameTo (File dest);
 
   /**
@@ -1194,7 +1213,7 @@ public class File implements Serializable, Comparable
    * @exception SecurityException If write access is not allowed to the 
    * file by the <code>SecurityMananger</code>.
    */
-  public boolean renameTo (File dest)
+  public synchronized boolean renameTo (File dest)
   {
     SecurityManager s = System.getSecurityManager();
     String sname = getName();
@@ -1207,6 +1226,9 @@ public class File implements Serializable, Comparable
     return performRenameTo (dest);
   }
 
+  /*
+   * This method does the actual setting of the modification time.
+   */
   private native boolean performSetLastModified(long time);
  
   /**
@@ -1225,7 +1247,7 @@ public class File implements Serializable, Comparable
    *
    * @since 1.2
    */
-  public boolean setLastModified(long time)
+  public boolean setLastModified (long time) 
   {
     checkWrite();
     return performSetLastModified(time);
@@ -1233,16 +1255,20 @@ public class File implements Serializable, Comparable
 
   private void checkWrite ()
   {
-    SecurityManager s = System.getSecurityManager();
+    // Check the SecurityManager
+    SecurityManager s = System.getSecurityManager ();
+    
     if (s != null)
-      s.checkWrite(path);
+      s.checkWrite (path);
   }
 
   private void checkRead ()
   {
-    SecurityManager s = System.getSecurityManager();
+    // Check the SecurityManager
+    SecurityManager s = System.getSecurityManager ();
+    
     if (s != null)
-      s.checkRead(path);
+      s.checkRead (path);
   }
 
   /** 
@@ -1254,6 +1280,7 @@ public class File implements Serializable, Comparable
   // FIXME: This should use the ShutdownHook API once we implement that.
   public void deleteOnExit ()
   {
+    // Check the SecurityManager
     SecurityManager sm = System.getSecurityManager ();
     if (sm != null)
       sm.checkDelete (getName ());
@@ -1275,8 +1302,9 @@ public class File implements Serializable, Comparable
     // If the file was from an OS with a different dir separator,
     // fixup the path to use the separator on this OS.
     char oldSeparatorChar = ois.readChar ();
+    
     if (oldSeparatorChar != separatorChar)
       path = path.replace (oldSeparatorChar, separatorChar);
   }
+} // class File
 
-}
diff --git a/libjava/java/io/FileInputStream.java b/libjava/java/io/FileInputStream.java
index b49922e..e22a23a 100644
--- a/libjava/java/io/FileInputStream.java
+++ b/libjava/java/io/FileInputStream.java
@@ -82,6 +82,7 @@ public class FileInputStream extends InputStream
     SecurityManager s = System.getSecurityManager();
     if (s != null)
       s.checkRead(name);
+
     fd = new FileDescriptor(name, FileDescriptor.READ);
   }
 
@@ -268,15 +269,15 @@ public class FileInputStream extends InputStream
    *
    * @exception IOException If an error occurs
    */
-  public long skip (long numBytes) throws IOException
+  public synchronized long skip (long numBytes) throws IOException
   {
     if (numBytes < 0)
-      throw new IllegalArgumentException ( "Can't skip negative bytes: " +
-                                           numBytes);
+      throw new IllegalArgumentException ("Can't skip negative bytes: " + 
+                                          numBytes);
 
     if (numBytes == 0)
       return 0;
-    
+
     long curPos = fd.getFilePointer ();
     long newPos = fd.seek (numBytes, FileDescriptor.CUR, true);
     return newPos - curPos;
diff --git a/libjava/java/io/FileOutputStream.java b/libjava/java/io/FileOutputStream.java
index 1c75ccd..f4488dc 100644
--- a/libjava/java/io/FileOutputStream.java
+++ b/libjava/java/io/FileOutputStream.java
@@ -233,7 +233,7 @@ public class FileOutputStream extends OutputStream
   public void write (byte[] buf)
     throws IOException
   {
-    fd.write (buf, 0, buf.length);
+    write (buf, 0, buf.length);
   }
 
   /**
diff --git a/libjava/java/io/InputStreamReader.java b/libjava/java/io/InputStreamReader.java
index 70213b5..d01541d 100644
--- a/libjava/java/io/InputStreamReader.java
+++ b/libjava/java/io/InputStreamReader.java
@@ -37,17 +37,54 @@ exception statement from your version. */
 
 
 package java.io;
+
 import gnu.gcj.convert.*;
 
 /**
+ * This class reads characters from a byte input stream.   The characters
+ * read are converted from bytes in the underlying stream by a 
+ * decoding layer.  The decoding layer transforms bytes to chars according
+ * to an encoding standard.  There are many available encodings to choose 
+ * from.  The desired encoding can either be specified by name, or if no
+ * encoding is selected, the system default encoding will be used.  The
+ * system default encoding name is determined from the system property
+ * <code>file.encoding</code>.  The only encodings that are guaranteed to 
+ * be availalbe are "8859_1" (the Latin-1 character set) and "UTF8".
+ * Unforunately, Java does not provide a mechanism for listing the
+ * ecodings that are supported in a given implementation.
+ * <p>
+ * Here is a list of standard encoding names that may be available:
+ * <p>
+ * <ul>
+ * <li>8859_1 (ISO-8859-1/Latin-1)
+ * <li>8859_2 (ISO-8859-2/Latin-2)
+ * <li>8859_3 (ISO-8859-3/Latin-3)
+ * <li>8859_4 (ISO-8859-4/Latin-4)
+ * <li>8859_5 (ISO-8859-5/Latin-5)
+ * <li>8859_6 (ISO-8859-6/Latin-6)
+ * <li>8859_7 (ISO-8859-7/Latin-7)
+ * <li>8859_8 (ISO-8859-8/Latin-8)
+ * <li>8859_9 (ISO-8859-9/Latin-9)
+ * <li>ASCII (7-bit ASCII)
+ * <li>UTF8 (UCS Transformation Format-8)
+ * <li>More later
+ * </ul>
+ * <p>
+ * It is recommended that applications do not use 
+ * <code>InputStreamReader</code>'s
+ * directly.  Rather, for efficiency purposes, an object of this class
+ * should be wrapped by a <code>BufferedReader</code>.
+ * <p>
+ * Due to a deficiency the Java class library design, there is no standard
+ * way for an application to install its own byte-character encoding.
+ *
+ * @see BufferedReader
+ * @see InputStream
+ *
+ * @author Aaron M. Renn (arenn@urbanophile.com)
  * @author Per Bothner <bothner@cygnus.com>
  * @date April 22, 1998.  
  */
-/* Written using "Java Class Libraries", 2nd edition, plus online
- * API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct, but only supports 8859_1.
- */
-
 public class InputStreamReader extends Reader
 {
   BufferedInputStream in;
@@ -61,11 +98,29 @@ public class InputStreamReader extends Reader
 
   BytesToUnicode converter;
 
+  /**
+   * This method initializes a new instance of <code>InputStreamReader</code>
+   * to read from the specified stream using the default encoding.
+   *
+   * @param in The <code>InputStream</code> to read from 
+   */
   public InputStreamReader(InputStream in)
   {
     this(in, BytesToUnicode.getDefaultDecoder());
   }
 
+  /**
+   * This method initializes a new instance of <code>InputStreamReader</code>
+   * to read from the specified stream using a caller supplied character
+   * encoding scheme.  Note that due to a deficiency in the Java language
+   * design, there is no way to determine which encodings are supported.
+   * 
+   * @param in The <code>InputStream</code> to read from
+   * @param encoding_name The name of the encoding scheme to use
+   *
+   * @exception UnsupportedEncodingException If the encoding scheme 
+   * requested is not available.
+   */
   public InputStreamReader(InputStream in, String encoding_name)
     throws UnsupportedEncodingException
   {