2003-03-31 Michael Koch <konqueror@gmx.de>

	* java/io/File.java
	(separator): Merged documentation from classpath.
	(separatorChar): Merged documentation from classpath.
	(pathSeparator): Merged documentation from classpath.
	(pathSeparatorChar): Merged documentation from classpath.
	(path): Merged documentation from classpath.
	(canRead): Merged documentation from classpath.
	(canWrite): Merged documentation from classpath.
	(createNewFile): Merged documentation from classpath.
	(delete): Merged documentation from classpath.
	(equals): Merged documentation from classpath.
	(exists): Merged documentation from classpath.
	(File): Renamed p to name to match classpath, merged documentation
	from classpath.
	(getAbsolutePath): Merged documentation from classpath.
	(getCanonicalPath): Merged documentation from classpath.
	(getCanonicalFile): Merged documentation from classpath.
	(getName): Merged documentation from classpath.
	(getParent): Merged documentation from classpath.
	(getParentFile): Merged documentation from classpath.
	(getPath): Merged documentation from classpath.
	(hashCode): Merged documentation from classpath.
	(isAbsolute): Merged documentation from classpath.
	(isDirectory): Merged documentation from classpath.
	(isFile): Merged documentation from classpath.
	(isHidden): Merged documentation from classpath.
	(lastModified): Merged documentation from classpath.
	(length): Merged documentation from classpath.
	(list): Merged documentation from classpath.
	(listFiles): Merged documentation from classpath.
	(toString): Merged documentation from classpath.
	(toURL): Merged documentation from classpath.
	(mkdir): Merged documentation from classpath.
	(mkdirs): Merged documentation from classpath.
	(createTempFile): Merged documentation from classpath.
	(setReadOnly): Merged documentation from classpath.
	(listRoots): Merged documentation from classpath.
	(compareTo): Merged documentation from classpath.
	(renameTo): Merged documentation from classpath.
	(setLastModified): Merged documentation from classpath.
	* java/io/PrintStream.java
	(auto_flush): Merged documentation from classpath.
	(PrintStream): Merged documentation from classpath.
	(checkError): Merged documentation from classpath.
	(setError): Merged documentation from classpath.
	(close): Merged documentation from classpath.
	(flush): Merged documentation from classpath.
	(print): Merged documentation from classpath.
	(println):  Merged documentation from classpath.
	(write): Renamed count to len to match classpath,
	merged documentation from classpath.
	* java/io/RandomAccessFile.java
	(readShort): Merged documentation from classpath.
	(readUnsignedByte): Merged documentation from classpath.
	(readUnsignedShort): Merged documentation from classpath.
	(readUTF): Merged documentation from classpath.
	(seek): Reformatted, merged documentation from classpath.
	(skipBytes): Renamed some variables to match classpath, reformatted,
	merged documentation from classpath.
	(write): Merged documentation from classpath.
	(writeBoolean): Merged documentation from classpath.
	(writeByte): Merged documentation from classpath.
	(writeShort): Merged documentation from classpath.
	(writeChar): Merged documentation from classpath.
	(writeInt): Merged documentation from classpath.
	(writeLong): Merged documentation from classpath.
	(writeFloat): Merged documentation from classpath.
	(writeDouble): Merged documentation from classpath.
	(writeBytes): Merged documentation from classpath.
	(writeChars): Merged documentation from classpath.
	(writeUTF): Reformatted.
	(getChannel): Reformatted.

From-SVN: r65081

4 files changed, 1175 insertions, 61 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index c685a6e..b131174 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,5 +1,80 @@
 2003-03-31  Michael Koch  <konqueror@gmx.de>
 
+	* java/io/File.java
+	(separator): Merged documentation from classpath.
+	(separatorChar): Merged documentation from classpath.
+	(pathSeparator): Merged documentation from classpath.
+	(pathSeparatorChar): Merged documentation from classpath.
+	(path): Merged documentation from classpath.
+	(canRead): Merged documentation from classpath.
+	(canWrite): Merged documentation from classpath.
+	(createNewFile): Merged documentation from classpath.
+	(delete): Merged documentation from classpath.
+	(equals): Merged documentation from classpath.
+	(exists): Merged documentation from classpath.
+	(File): Renamed p to name to match classpath, merged documentation
+	from classpath.
+	(getAbsolutePath): Merged documentation from classpath.
+	(getCanonicalPath): Merged documentation from classpath.
+	(getCanonicalFile): Merged documentation from classpath.
+	(getName): Merged documentation from classpath.
+	(getParent): Merged documentation from classpath.
+	(getParentFile): Merged documentation from classpath.
+	(getPath): Merged documentation from classpath.
+	(hashCode): Merged documentation from classpath.
+	(isAbsolute): Merged documentation from classpath.
+	(isDirectory): Merged documentation from classpath.
+	(isFile): Merged documentation from classpath.
+	(isHidden): Merged documentation from classpath.
+	(lastModified): Merged documentation from classpath.
+	(length): Merged documentation from classpath.
+	(list): Merged documentation from classpath.
+	(listFiles): Merged documentation from classpath.
+	(toString): Merged documentation from classpath.
+	(toURL): Merged documentation from classpath.
+	(mkdir): Merged documentation from classpath.
+	(mkdirs): Merged documentation from classpath.
+	(createTempFile): Merged documentation from classpath.
+	(setReadOnly): Merged documentation from classpath.
+	(listRoots): Merged documentation from classpath.
+	(compareTo): Merged documentation from classpath.
+	(renameTo): Merged documentation from classpath.
+	(setLastModified): Merged documentation from classpath.
+	* java/io/PrintStream.java
+	(auto_flush): Merged documentation from classpath.
+	(PrintStream): Merged documentation from classpath.
+	(checkError): Merged documentation from classpath.
+	(setError): Merged documentation from classpath.
+	(close): Merged documentation from classpath.
+	(flush): Merged documentation from classpath.
+	(print): Merged documentation from classpath.
+	(println):  Merged documentation from classpath.
+	(write): Renamed count to len to match classpath,
+	merged documentation from classpath.
+	* java/io/RandomAccessFile.java
+	(readShort): Merged documentation from classpath.
+	(readUnsignedByte): Merged documentation from classpath.
+	(readUnsignedShort): Merged documentation from classpath.
+	(readUTF): Merged documentation from classpath.
+	(seek): Reformatted, merged documentation from classpath.
+	(skipBytes): Renamed some variables to match classpath, reformatted,
+	merged documentation from classpath.
+	(write): Merged documentation from classpath.
+	(writeBoolean): Merged documentation from classpath.
+	(writeByte): Merged documentation from classpath.
+	(writeShort): Merged documentation from classpath.
+	(writeChar): Merged documentation from classpath.
+	(writeInt): Merged documentation from classpath.
+	(writeLong): Merged documentation from classpath.
+	(writeFloat): Merged documentation from classpath.
+	(writeDouble): Merged documentation from classpath.
+	(writeBytes): Merged documentation from classpath.
+	(writeChars): Merged documentation from classpath.
+	(writeUTF): Reformatted.
+	(getChannel): Reformatted.
+
+2003-03-31  Michael Koch  <konqueror@gmx.de>
+
 	* java/awt/font/TextAttribute.java
 	(readResolve): Throws java.io.InvalidObjectException.
 
diff --git a/libjava/java/io/File.java b/libjava/java/io/File.java
index 61dedff..83e4c2e 100644
--- a/libjava/java/io/File.java
+++ b/libjava/java/io/File.java
@@ -81,12 +81,94 @@ public class File implements Serializable, Comparable
   private final native boolean _access (int query);
   private final native boolean _stat (int query);
 
+  /**
+   * This is the path separator string for the current host. This field
+   * contains the value of the <code>file.separator</code> system property.
+   * An example separator string would be "/" on the GNU system.
+   */
+  public static final String separator = System.getProperty("file.separator");
+
+  /**
+   * This is the first character of the file separator string.  On many
+   * hosts (for example, on the GNU system), this represents the entire 
+   * separator string.  The complete separator string is obtained from the
+   * <code>file.separator</code>system property.
+   */
+  public static final char separatorChar = separator.charAt(0);
+  
+  /**
+   * This is the string that is used to separate the host name from the
+   * path name in paths than include the host name.  It is the value of
+   * the <code>path.separator</code> system property.
+   */
+  public static final String pathSeparator
+    = System.getProperty("path.separator");
+  
+  /**
+   * This is the first character of the string used to separate the host name
+   * from the path name in paths that include a host.  The separator string
+   * is taken from the <code>path.separator</code> system property.
+   */
+  public static final char pathSeparatorChar = pathSeparator.charAt(0);
+  
+
+  static final String tmpdir = System.getProperty("java.io.tmpdir");
+  static int maxPathLen;
+  static boolean caseSensitive;
+  static String dupSeparator = separator + separator;
+  
+  static
+  {
+    init_native();
+  }
+  
+  // Native function called at class initialization. This should should
+  // set the maxPathLen and caseSensitive variables.
+  private static native void init_native();
+
+  /**
+   * This is the path to the file set when the object is created.  It
+   * may be an absolute or relative path name.
+   */
+  private String path;
+
+  // We keep a counter for use by createTempFile.  We choose the first
+  // value randomly to try to avoid clashes with other VMs.
+  private static long counter = Double.doubleToLongBits (Math.random ());
+
+  /**
+   * This method tests whether or not the current thread is allowed to
+   * to read the file pointed to by this object.  This will be true if and
+   * and only if 1) the file exists and 2) the <code>SecurityManager</code>
+   * (if any) allows access to the file via it's <code>checkRead</code>
+   * method 3) the file is readable.
+   *
+   * @return <code>true</code> if reading is allowed, 
+   * <code>false</code> otherwise
+   *
+   * @exception SecurityException If the <code>SecurityManager</code> 
+   * does not allow access to the file
+   */
   public boolean canRead ()
   {
     checkRead();
     return _access (READ);
   }
 
+  /**
+   * This method test whether or not the current thread is allowed to
+   * write to this object.  This will be true if and only if 1) The
+   * <code>SecurityManager</code> (if any) allows write access to the
+   * file and 2) The file exists and 3) The file is writable.  To determine
+   * whether or not a non-existent file can be created, check the parent
+   * directory for write access.
+   *
+   * @return <code>true</code> if writing is allowed, <code>false</code> 
+   * otherwise
+   *
+   * @exception SecurityException If the <code>SecurityManager</code> 
+   * does not allow access to the file
+   */
   public boolean canWrite ()
   {
     checkWrite();
@@ -95,7 +177,23 @@ public class File implements Serializable, Comparable
   
   private native boolean performCreate() throws IOException;
 
-  /** @since 1.2 */
+  /**
+   * This method creates a new file of zero length with the same name as
+   * the path of this <code>File</code> object if an only if that file
+   * does not already exist.
+   * <p>
+   * A <code>SecurityManager</code>checkWrite</code> check is done prior
+   * to performing this action.
+   *
+   * @return <code>true</code> if the file was created, <code>false</code> if
+   * the file alread existed.
+   *
+   * @exception IOException If an I/O error occurs
+   * @exception SecurityException If the <code>SecurityManager</code> will
+   * not allow this operation to be performed.
+   *
+   * @since 1.2
+   */
   public boolean createNewFile() throws IOException
   {
     checkWrite();
@@ -103,6 +201,16 @@ public class File implements Serializable, Comparable
   }
   
   private native boolean performDelete ();
+
+  /**
+   * This method deletes the file represented by this object.  If this file
+   * is a directory, it must be empty in order for the delete to succeed.
+   *
+   * @return <code>true</code> if the file was deleted, <code>false</code> 
+   * otherwise
+   *
+   * @exception SecurityException If deleting of the file is not allowed
+   */
   public boolean delete ()
   {
     SecurityManager s = System.getSecurityManager();
@@ -112,6 +220,21 @@ public class File implements Serializable, Comparable
     return performDelete ();
   }
 
+  /**
+   * This method tests two <code>File</code> objects for equality by 
+   * comparing the path of the specified <code>File</code> against the path
+   * of this object.  The two objects are equal if an only if 1) The
+   * argument is not null 2) The argument is a <code>File</code> object and
+   * 3) The path of the <code>File</code>argument is equal to the path
+   * of this object.
+   * <p>
+   * The paths of the files are determined by calling the 
+   * <code>getPath()</code>
+   * method on each object.
+   *
+   * @return <code>true</code> if the two objects are equal, 
+   * <code>false</code> otherwise.
+   */
   public boolean equals (Object obj)
   {
     if (! (obj instanceof File))
@@ -123,15 +246,29 @@ public class File implements Serializable, Comparable
       return (path.equalsIgnoreCase(other.path));      
   }
 
+  /**
+   * This method tests whether or not the file represented by the object
+   * actually exists on the filesystem.
+   *
+   * @return <code>true</code> if the file exists, <code>false</code>otherwise.
+   *
+   * @exception SecurityException If reading of the file is not permitted
+   */
   public boolean exists ()
   {
     checkRead();
     return _access (EXISTS);
   }
 
-  public File (String p)
+  /**
+   * This method initializes a new <code>File</code> object to represent
+   * a file with the specified path.
+   *
+   * @param name The path name of the file
+   */
+  public File (String name)
   {
-    path = normalizePath(p);
+    path = normalizePath (name);
   }
 
   // Remove duplicate and redundant separator characters.
@@ -195,7 +332,17 @@ public class File implements Serializable, Comparable
     
     return newpath.toString();
   }
-  
+ 
+  /**
+   * This method initializes a new <code>File</code> object to represent
+   * a file in the specified named directory.  The path name to the file
+   * will be the directory name plus the separator string plus the file
+   * name.  If the directory path name ends in the separator string, another
+   * separator string will still be appended.
+   *
+   * @param dirname The path to the directory the file resides in
+   * @param name The name of the file
+   */
   public File (String dirPath, String name)
   {
     if (name == null)
@@ -213,11 +360,30 @@ public class File implements Serializable, Comparable
       path = normalizePath(name);
   }
 
-  public File (File dir, String name)
+  /**
+   * This method initializes a new <code>File</code> object to represent
+   * a file in the specified directory.  If the <code>directory</code>
+   * argument is <code>null</code>, the file is assumed to be in the
+   * current directory as specified by the <code>user.dir</code> system
+   * property
+   *
+   * @param directory The directory this file resides in
+   * @param name The name of the file
+   */
+  public File (File directory, String name)
   {
-    this (dir == null ? null : dir.path, name);
+    this (directory == null ? null : directory.path, name);
   }
 
+  /**
+   * This method returns the path of this file as an absolute path name.
+   * If the path name is already absolute, then it is returned.  Otherwise
+   * the value returned is the current directory plus the separatory
+   * string plus the path of the file.  The current directory is determined
+   * from the <code>user.dir</code> system property.
+   *
+   * @return The absolute path of this file
+   */
   public String getAbsolutePath ()
   {
     if (isAbsolute ())
@@ -234,26 +400,70 @@ public class File implements Serializable, Comparable
       return System.getProperty ("user.dir") + separatorChar + path;
   }
 
-  /** @since 1.2 */
+  /**
+   * This method returns a <code>File</code> object representing the
+   * absolute path of this object.
+   *
+   * @return A <code>File</code> with the absolute path of the object.
+   *
+   * @since 1.2
+   */
   public File getAbsoluteFile ()
   {
     return new File (getAbsolutePath());
   }
 
+  /**
+   * This method returns a canonical representation of the pathname of
+   * this file.  The actual form of the canonical representation is
+   * different.  On the GNU system, the canonical form differs from the
+   * absolute form in that all relative file references to "." and ".."
+   * are resolved and removed.
+   * <p>
+   * Note that this method, unlike the other methods which return path
+   * names, can throw an IOException.  This is because native method 
+   * might be required in order to resolve the canonical path
+   *
+   * @exception IOException If an error occurs
+   */
   public native String getCanonicalPath () throws IOException;
 
-  /** @since 1.2 */
+  /**
+   * This method returns a <code>File</code> object representing the
+   * canonical path of this object.
+   *
+   * @return A <code>File</code> instance representing the canonical path of
+   * this object.
+   *
+   * @exception IOException If an error occurs.
+   *
+   * @since 1.2
+   */
   public File getCanonicalFile () throws IOException
   {
     return new File (getCanonicalPath());
   }
 
+  /**
+   * This method returns the name of the file.  This is everything in the
+   * complete path of the file after the last instance of the separator
+   * string.
+   *
+   * @return The file name
+   */
   public String getName ()
   {
     int last = path.lastIndexOf(separatorChar);
     return path.substring(last + 1);
   }
 
+  /**
+   * This method returns a <code>String</code> the represents this file's
+   * parent.  <code>null</code> is returned if the file has no parent.  The
+   * parent is determined via a simple operation which removes the
+   *
+   * @return The parent directory of this file
+   */
   public String getParent ()
   {
     int last = path.lastIndexOf(separatorChar);
@@ -265,18 +475,40 @@ public class File implements Serializable, Comparable
     return path.substring(0, last);
   }
 
-  /** @since 1.2 */
+  /**
+   * This method returns a <code>File</code> object representing the parent
+   * file of this one.
+   *
+   * @param A <code>File</code> for the parent of this object.  
+   * <code>null</code>
+   * will be returned if this object does not have a parent.
+   *
+   * @since 1.2
+   */
   public File getParentFile ()
   {
     String parent = getParent ();
     return (parent == null ? null : new File (parent));
   }
 
+  /**
+   * Returns the path name that represents this file.  May be a relative
+   * or an absolute path name
+   *
+   * @return The pathname of this file
+   */
   public String getPath ()
   {
     return path;
   }
 
+  /**
+   * This method returns a hash code representing this file.  It is the
+   * hash code of the path of this file (as returned by <code>getPath()</code>)
+   * exclusived or-ed with the value 1234321.
+   *
+   * @return The hash code for this object
+   */
   public int hashCode ()
   {
     if (caseSensitive)
@@ -285,33 +517,93 @@ public class File implements Serializable, Comparable
       return (path.toLowerCase().hashCode() ^ 1234321);
   }
 
+  /**
+   * This method returns true if this object represents an absolute file
+   * path and false if it does not.  The definition of an absolute path varies
+   * by system.  As an example, on GNU systems, a path is absolute if it starts
+   * with a "/".
+   *
+   * @return <code>true</code> if this object represents an absolute 
+   * file name, <code>false</code> otherwise.
+   */
   public native boolean isAbsolute ();
 
+  /**
+   * This method tests whether or not the file represented by this object
+   * is a directory.  In order for this method to return <code>true</code>,
+   * the file represented by this object must exist and be a directory.
+   * 
+   * @return <code>true</code> if this file is a directory, <code>false</code>
+   * otherwise
+   *
+   * @exception SecurityException If reading of the file is not permitted
+   */
   public boolean isDirectory ()
   {
     checkRead();
     return _stat (DIRECTORY);
   }
 
+  /**
+   * This method tests whether or not the file represented by this object
+   * is a "plain" file.  A file is a plain file if and only if it 1) Exists,
+   * 2) Is not a directory or other type of special file.
+   *
+   * @return <code>true</code> if this is a plain file, <code>false</code> 
+   * otherwise
+   *
+   * @exception SecurityException If reading of the file is not permitted
+   */
   public boolean isFile ()
   {
     checkRead();
     return _stat (ISFILE);
   }
 
-  /** @since 1.2 */
+  /**
+   * This method tests whether or not this file represents a "hidden" file.
+   * On GNU systems, a file is hidden if its name begins with a "."
+   * character.  Files with these names are traditionally not shown with
+   * directory listing tools.
+   *
+   * @return <code>true</code> if the file is hidden, <code>false</code>
+   * otherwise.
+   *
+   * @since 1.2
+   */
   public boolean isHidden()
   {
     checkRead();
     return _stat (ISHIDDEN);
   }
 
+  /**
+   * This method returns the last modification time of this file.  The
+   * time value returned is an abstract value that should not be interpreted
+   * as a specified time value.  It is only useful for comparing to other
+   * such time values returned on the same system.  In that case, the larger
+   * value indicates a more recent modification time. 
+   * <p>
+   * If the file does not exist, then a value of 0 is returned.
+   *
+   * @return The last modification time of the file
+   *
+   * @exception SecurityException If reading of the file is not permitted
+   */
   public long lastModified ()
   {
     checkRead();
     return attr (MODIFIED);
   }
 
+  /**
+   * This method returns the length of the file represented by this object,
+   * or 0 if the specified file does not exist.
+   *
+   * @return The length of the file
+   *
+   * @exception SecurityException If reading of the file is not permitted
+   */
   public long length ()
   {
     checkRead();
@@ -322,44 +614,168 @@ public class File implements Serializable, Comparable
 					     FileFilter fileFilter,
 					     Class result_type);
 
+  /**
+   * This method returns a array of <code>String</code>'s representing the
+   * list of files is then directory represented by this object.  If this
+   * object represents a non-directory file or a non-existent file, then
+   * <code>null</code> is returned.  The list of files will not contain
+   * any names such as "." or ".." which indicate the current or parent
+   * directory.  Also, the names are not guaranteed to be sorted.
+   * <p>
+   * In this form of the <code>list()</code> method, a filter is specified
+   * that allows the caller to control which files are returned in the
+   * list.  The <code>FilenameFilter</code> specified is called for each
+   * file returned to determine whether or not that file should be included
+   * in the list.
+   * <p>
+   * A <code>SecurityManager</code> check is made prior to reading the
+   * directory.  If read access to the directory is denied, an exception
+   * will be thrown.
+   *
+   * @param filter An object which will identify files to exclude from 
+   * the directory listing.
+   *
+   * @return An array of files in the directory, or <code>null</code> 
+   * if this object does not represent a valid directory.
+   * 
+   * @exception SecurityException If read access is not allowed to the 
+   * directory by the <code>SecurityManager</code>
+   */
   public String[] list (FilenameFilter filter)
   {
     checkRead();
     return (String[]) performList (filter, null, String.class);
   }
 
+  /**
+   * This method returns a array of <code>String</code>'s representing the
+   * list of files is then directory represented by this object.  If this
+   * object represents a non-directory file or a non-existent file, then
+   * <code>null</code> is returned.  The list of files will not contain
+   * any names such as "." or ".." which indicate the current or parent
+   * directory.  Also, the names are not guaranteed to be sorted.
+   * <p>
+   * A <code>SecurityManager</code> check is made prior to reading the
+   * directory.  If read access to the directory is denied, an exception
+   * will be thrown.
+   *
+   * @return An array of files in the directory, or <code>null</code> if 
+   * this object does not represent a valid directory.
+   * 
+   * @exception SecurityException If read access is not allowed to the 
+   * directory by the <code>SecurityManager</code>
+   */
   public String[] list ()
   {
     checkRead();
     return (String[]) performList (null, null, String.class);
   }
 
-  /** @since 1.2 */
+  /**
+   * This method returns an array of <code>File</code> objects representing
+   * all the files in the directory represented by this object. If this
+   * object does not represent a directory, <code>null</code> is returned.
+   * Each of the returned <code>File</code> object is constructed with this
+   * object as its parent.
+   * <p>
+   * A <code>SecurityManager</code> check is made prior to reading the
+   * directory.  If read access to the directory is denied, an exception
+   * will be thrown.
+   *
+   * @return An array of <code>File</code> objects for this directory.
+   *
+   * @exception SecurityException If the <code>SecurityManager</code> denies
+   * access to this directory.
+   *
+   * @since 1.2
+   */
   public File[] listFiles()
   {
     checkRead();
     return (File[]) performList (null, null, File.class);
   }
   
-  /** @since 1.2 */
+  /**
+   * This method returns an array of <code>File</code> objects representing
+   * all the files in the directory represented by this object. If this
+   * object does not represent a directory, <code>null</code> is returned.
+   * Each of the returned <code>File</code> object is constructed with this
+   * object as its parent.
+   * <p> 
+   * In this form of the <code>listFiles()</code> method, a filter is specified
+   * that allows the caller to control which files are returned in the
+   * list.  The <code>FilenameFilter</code> specified is called for each
+   * file returned to determine whether or not that file should be included
+   * in the list.
+   * <p>
+   * A <code>SecurityManager</code> check is made prior to reading the
+   * directory.  If read access to the directory is denied, an exception
+   * will be thrown.
+   *
+   * @return An array of <code>File</code> objects for this directory.
+   *
+   * @exception SecurityException If the <code>SecurityManager</code> denies
+   * access to this directory.
+   *
+   * @since 1.2
+   */
   public File[] listFiles(FilenameFilter filter)
   {
     checkRead();
     return (File[]) performList (filter, null, File.class);
   }
   
-  /** @since 1.2 */
+  /**
+   * This method returns an array of <code>File</code> objects representing
+   * all the files in the directory represented by this object. If this
+   * object does not represent a directory, <code>null</code> is returned.
+   * Each of the returned <code>File</code> object is constructed with this
+   * object as its parent.
+   * <p> 
+   * In this form of the <code>listFiles()</code> method, a filter is specified
+   * that allows the caller to control which files are returned in the
+   * list.  The <code>FileFilter</code> specified is called for each
+   * file returned to determine whether or not that file should be included
+   * in the list.
+   * <p>
+   * A <code>SecurityManager</code> check is made prior to reading the
+   * directory.  If read access to the directory is denied, an exception
+   * will be thrown.
+   *
+   * @return An array of <code>File</code> objects for this directory.
+   *
+   * @exception SecurityException If the <code>SecurityManager</code> denies
+   * access to this directory.
+   *
+   * @since 1.2
+   */
   public File[] listFiles(FileFilter filter)
   {
     checkRead();
     return (File[]) performList (null, filter, File.class);
   }
 
+  /**
+   * This method returns a <code>String</code> that is the path name of the
+   * file as returned by <code>getPath</code>.
+   *
+   * @return A <code>String</code> representation of this file
+   */
   public String toString ()
   {
     return path;
   }
 
+  /**
+   * This method returns a <code>URL</code> with the <code>file:</code>
+   * protocol that represents this file.  The exact form of this URL is
+   * system dependent.
+   *
+   * @return A <code>URL</code> for this object.
+   *
+   * @exception MalformedURLException If the URL cannot be created 
+   * successfully.
+   */
   public URL toURL () throws MalformedURLException
   {
     // On Win32, Sun's JDK returns URLs of the form "file:/c:/foo/bar.txt",
@@ -374,6 +790,14 @@ public class File implements Serializable, Comparable
 
   private final native boolean performMkdir ();
 
+  /**
+   * This method creates a directory for the path represented by this object.
+   *
+   * @return <code>true</code> if the directory was created, 
+   * <code>false</code> otherwise
+   *
+   * @exception SecurityException If write access is not allowed to this file
+   */
   public boolean mkdir ()
   {
     checkWrite();
@@ -396,6 +820,15 @@ public class File implements Serializable, Comparable
     return x.mkdir();
   }
 
+  /**
+   * This method creates a directory for the path represented by this file.
+   * It will also create any intervening parent directories if necessary.
+   *
+   * @return <code>true</code> if the directory was created, 
+   * <code>false</code> otherwise
+   *
+   * @exception SecurityException If write access is not allowed to this file
+   */
   public boolean mkdirs ()
   {
     checkWrite();
@@ -409,7 +842,36 @@ public class File implements Serializable, Comparable
     return Long.toString(counter++, Character.MAX_RADIX);
   }
 
-  /** @since 1.2 */
+  /**
+   * This method creates a temporary file in the specified directory.  If 
+   * the directory name is null, then this method uses the system temporary 
+   * directory. The files created are guaranteed not to currently exist and 
+   * the same file name will never be used twice in the same virtual 
+   * machine instance.  
+   * The system temporary directory is determined by examinging the 
+   * <code>java.io.tmpdir</code> system property.
+   * <p>
+   * The <code>prefix</code> parameter is a sequence of at least three
+   * characters that are used as the start of the generated filename.  The
+   * <code>suffix</code> parameter is a sequence of characters that is used
+   * to terminate the file name.  This parameter may be <code>null</code>
+   * and if it is, the suffix defaults to ".tmp".
+   * <p>
+   * If a <code>SecurityManager</code> exists, then its <code>checkWrite</code>
+   * method is used to verify that this operation is permitted.
+   *
+   * @param prefix The character prefix to use in generating the path name.
+   * @param suffix The character suffix to use in generating the path name.
+   * @param directory The directory to create the file in, or 
+   * <code>null</code> for the default temporary directory
+   *
+   * @exception IllegalArgumentException If the patterns is not valid
+   * @exception SecurityException If there is no permission to perform 
+   * this operation
+   * @exception IOException If an error occurs
+   *
+   * @since 1.2
+   */
   public static File createTempFile (String prefix, String suffix,
 				     File directory)
     throws IOException
@@ -473,7 +935,20 @@ public class File implements Serializable, Comparable
 
   private native boolean performSetReadOnly();
 
-  /** @since 1.2 */
+  /**
+   * This method sets the file represented by this object to be read only.
+   * A read only file or directory cannot be modified.  Please note that 
+   * GNU systems allow read only files to be deleted if the directory it
+   * is contained in is writable.
+   *
+   * @return <code>true</code> if the operation succeeded, <code>false</code>
+   * otherwise.
+   *
+   * @exception SecurityException If the <code>SecurityManager</code> does
+   * not allow this operation.
+   *
+   * @since 1.2
+   */
   public boolean setReadOnly()
   {
     checkWrite();
@@ -482,7 +957,17 @@ public class File implements Serializable, Comparable
 
   private static native File[] performListRoots();
 
-  /** @since 1.2 */
+  /**
+   * This method returns an array of filesystem roots.  Some operating systems
+   * have volume oriented filesystem.  This method provides a mechanism for
+   * determining which volumes exist.  GNU systems use a single hierarchical
+   * filesystem, so will have only one "/" filesystem root.
+   *
+   * @return An array of <code>File</code> objects for each filesystem root
+   * available.
+   *
+   * @since 1.2
+   */
   public static File[] listRoots()
   {
     File[] roots = performListRoots();
@@ -519,13 +1004,55 @@ public class File implements Serializable, Comparable
     return roots;
   }
 
+  /**
+   * This method creates a temporary file in the system temporary directory. 
+   * The files created are guaranteed not to currently exist and the same file
+   * name will never be used twice in the same virtual machine instance.  The
+   * system temporary directory is determined by examinging the 
+   * <code>java.io.tmpdir</code> system property.
+   * <p>
+   * The <code>prefix</code> parameter is a sequence of at least three
+   * characters that are used as the start of the generated filename.  The
+   * <code>suffix</code> parameter is a sequence of characters that is used
+   * to terminate the file name.  This parameter may be <code>null</code>
+   * and if it is, the suffix defaults to ".tmp".
+   * <p>
+   * If a <code>SecurityManager</code> exists, then its <code>checkWrite</code>
+   * method is used to verify that this operation is permitted.
+   * <p>
+   * This method is identical to calling 
+   * <code>createTempFile(prefix, suffix, null)</code>.
+   *
+   * @param prefix The character prefix to use in generating the path name.
+   * @param suffix The character suffix to use in generating the path name.
+   *
+   * @exception IllegalArgumentException If the prefix or suffix are not valid.
+   * @exception SecurityException If there is no permission to perform 
+   * this operation
+   * @exception IOException If an error occurs
+   */
   public static File createTempFile (String prefix, String suffix)
     throws IOException
   {
     return createTempFile (prefix, suffix, null);
   }
 
-  /** @since 1.2 */
+  /**
+   * This method compares the specified <code>File</code> to this one
+   * to test for equality.  It does this by comparing the canonical path names
+   * of the files. 
+   * <p>
+   * The canonical paths of the files are determined by calling the
+   * <code>getCanonicalPath</code> method on each object.
+   * <p>
+   * This method returns a 0 if the specified <code>Object</code> is equal
+   * to this one, a negative value if it is less than this one 
+   * a positive value if it is greater than this one.
+   *
+   * @return An integer as described above
+   *
+   * @since 1.2
+   */
   public int compareTo(File other)
   {
     if (caseSensitive)
@@ -534,7 +1061,27 @@ public class File implements Serializable, Comparable
       return path.compareToIgnoreCase (other.path);
   }
 
-  /** @since 1.2 */
+  /**
+   * This method compares the specified <code>Object</code> to this one
+   * to test for equality.  It does this by comparing the canonical path names
+   * of the files.  This method is identical to <code>compareTo(File)</code>
+   * except that if the <code>Object</code> passed to it is not a 
+   * <code>File</code>, it throws a <code>ClassCastException</code>
+   * <p>
+   * The canonical paths of the files are determined by calling the
+   * <code>getCanonicalPath</code> method on each object.
+   * <p>
+   * This method returns a 0 if the specified <code>Object</code> is equal
+   * to this one, a negative value if it is less than this one 
+   * a positive value if it is greater than this one.
+   *
+   * @return An integer as described above
+   *
+   * @exception ClassCastException If the passed <code>Object</code> is 
+   * not a <code>File</code>
+   *
+   * @since 1.2
+   */
   public int compareTo(Object o)
   {
     File other = (File) o;
@@ -542,6 +1089,19 @@ public class File implements Serializable, Comparable
   }
 
   private native boolean performRenameTo (File dest);
+
+  /**
+   * This method renames the file represented by this object to the path
+   * of the file represented by the argument <code>File</code>.
+   *
+   * @param dest The <code>File</code> object representing the target name
+   *
+   * @return <code>true</code> if the rename succeeds, <code>false</code> 
+   * otherwise.
+   *
+   * @exception SecurityException If write access is not allowed to the 
+   * file by the <code>SecurityMananger</code>.
+   */
   public boolean renameTo (File dest)
   {
     SecurityManager s = System.getSecurityManager();
@@ -556,41 +1116,29 @@ public class File implements Serializable, Comparable
   }
 
   private native boolean performSetLastModified(long time);
-  
-  /** @since 1.2 */
+ 
+  /**
+   * This method sets the modification time on the file to the specified
+   * value.  This is specified as the number of seconds since midnight
+   * on January 1, 1970 GMT.
+   *
+   * @param time The desired modification time.
+   *
+   * @return <code>true</code> if the operation succeeded, <code>false</code>
+   * otherwise.
+   *
+   * @exception IllegalArgumentException If the specified time is negative.
+   * @exception SecurityException If the <code>SecurityManager</code> will
+   * not allow this operation.
+   *
+   * @since 1.2
+   */
   public boolean setLastModified(long time)
   {
     checkWrite();
     return performSetLastModified(time);
   }
 
-  public static final String pathSeparator
-    = System.getProperty("path.separator");
-  public static final char pathSeparatorChar = pathSeparator.charAt(0);
-  public static final String separator = System.getProperty("file.separator");
-  public static final char separatorChar = separator.charAt(0);
-
-  static final String tmpdir = System.getProperty("java.io.tmpdir");
-  static int maxPathLen;
-  static boolean caseSensitive;
-  static String dupSeparator = separator + separator;
-  
-  static
-  {
-    init_native();
-  }
-  
-  // Native function called at class initialization. This should should
-  // set the maxPathLen and caseSensitive variables.
-  private static native void init_native();
-
-  // The path.
-  private String path;
-
-  // We keep a counter for use by createTempFile.  We choose the first
-  // value randomly to try to avoid clashes with other VMs.
-  private static long counter = Double.doubleToLongBits (Math.random ());
-
   private void checkWrite ()
   {
     SecurityManager s = System.getSecurityManager();
diff --git a/libjava/java/io/PrintStream.java b/libjava/java/io/PrintStream.java
index 9563305..418d7f2 100644
--- a/libjava/java/io/PrintStream.java
+++ b/libjava/java/io/PrintStream.java
@@ -84,32 +84,76 @@ public class PrintStream extends FilterOutputStream
   // True if error occurred.
   private boolean error;
   // True if auto-flush.
+  /**
+   * This is <code>true</code> if auto-flush is enabled, 
+   * <code>false</code> otherwise
+   */
   private boolean auto_flush;
 
+  /**
+   * This method intializes a new <code>PrintStream</code> object to write
+   * to the specified output sink.  Note that this class is deprecated in
+   * favor of <code>PrintWriter</code>.
+   *
+   * @param out The <code>OutputStream</code> to write to.
+   *
+   * @deprecated
+   */
   public PrintStream (OutputStream out)
   {
     this(out, false);
   }
 
+  /**
+   * This method intializes a new <code>PrintStream</code> object to write
+   * to the specified output sink.  This constructor also allows "auto-flush"
+   * functionality to be specified where the stream will be flushed after
+   * every line is terminated or newline character is written.
+   * <p>
+   * Note that this class is deprecated in favor of <code>PrintWriter</code>.
+   *
+   * @param out The <code>OutputStream</code> to write to.
+   * @param auto_flush <code>true</code> to flush the stream after every 
+   * line, <code>false</code> otherwise
+   *
+   * @deprecated
+   */
   public PrintStream (OutputStream out, boolean auto_flush)
   {
     super(out);
+
     converter = UnicodeToBytes.getDefaultEncoder();
     error = false;
     this.auto_flush = auto_flush;
   }
 
+  /**
+   * This method checks to see if an error has occurred on this stream.  Note
+   * that once an error has occurred, this method will continue to report
+   * <code>true</code> forever for this stream.  Before checking for an
+   * error condition, this method flushes the stream.
+   *
+   * @return <code>true</code> if an error has occurred, 
+   * <code>false</code> otherwise
+   */
   public boolean checkError ()
   {
     flush();
     return error;
   }
 
+  /**
+   * This method can be called by subclasses to indicate that an error
+   * has occurred and should be reported by <code>checkError</code>.
+   */
   protected void setError ()
   {
     error = true;
   }
 
+  /**
+   * This method closes this stream and all underlying streams.
+   */
   public void close ()
   {
     try
@@ -127,6 +171,10 @@ public class PrintStream extends FilterOutputStream
       }
   }
 
+  /**
+   * This method flushes any buffered bytes to the underlying stream and
+   * then flushes that stream as well.
+   */
   public void flush ()
   {
     try
@@ -210,103 +258,245 @@ public class PrintStream extends FilterOutputStream
       }
   }
 
+  /**
+   * This methods prints a boolean value to the stream.  <code>true</code>
+   * values are printed as "true" and <code>false</code> values are printed
+   * as "false".
+   *
+   * @param b The <code>boolean</code> value to print
+   */
   public void print (boolean bool)
   {
     print(String.valueOf(bool), false);
   }
 
+  /**
+   * This method prints an integer to the stream.  The value printed is
+   * determined using the <code>String.valueOf()</code> method.
+   *
+   * @param inum The <code>int</code> value to be printed
+   */
   public void print (int inum)
   {
     print(String.valueOf(inum), false);
   }
 
+  /**
+   * This method prints a long to the stream.  The value printed is
+   * determined using the <code>String.valueOf()</code> method.
+   *
+   * @param lnum The <code>long</code> value to be printed
+   */
   public void print (long lnum)
   {
     print(String.valueOf(lnum), false);
   }
 
+  /**
+   * This method prints a float to the stream.  The value printed is
+   * determined using the <code>String.valueOf()</code> method.
+   *
+   * @param fnum The <code>float</code> value to be printed
+   */
   public void print (float fnum)
   {
     print(String.valueOf(fnum), false);
   }
 
+  /**
+   * This method prints a double to the stream.  The value printed is
+   * determined using the <code>String.valueOf()</code> method.
+   *
+   * @param dnum The <code>double</code> value to be printed
+   */
   public void print (double dnum)
   {
     print(String.valueOf(dnum), false);
   }
 
+  /**
+   * This method prints an <code>Object</code> to the stream.  The actual
+   * value printed is determined by calling the <code>String.valueOf()</code>
+   * method.
+   *
+   * @param obj The <code>Object</code> to print.
+   */
   public void print (Object obj)
   {
     print(obj == null ? "null" : obj.toString(), false);
   }
 
+  /**
+   * This method prints a <code>String</code> to the stream.  The actual
+   * value printed depends on the system default encoding.
+   *
+   * @param str The <code>String</code> to print.
+   */
   public void print (String str)
   {
     print(str == null ? "null" : str, false);
   }
 
+  /**
+   * This method prints a char to the stream.  The actual value printed is
+   * determined by the character encoding in use.
+   *
+   * @param ch The <code>char</code> value to be printed
+   */
   public synchronized void print (char ch)
   {
     work[0] = ch;
     print(work, 0, 1, false);
   }
 
+  /**
+   * This method prints an array of characters to the stream.  The actual
+   * value printed depends on the system default encoding.
+   *
+   * @param s The array of characters to print.
+   */
   public void print (char[] charArray)
   {
     print(charArray, 0, charArray.length, false);
   }
 
+  /**
+   * This method prints a line separator sequence to the stream.  The value
+   * printed is determined by the system property <xmp>line.separator</xmp>
+   * and is not necessarily the Unix '\n' newline character.
+   */
   public void println ()
   {
     print(line_separator, 0, line_separator.length, false);
   }
 
+  /**
+   * This methods prints a boolean value to the stream.  <code>true</code>
+   * values are printed as "true" and <code>false</code> values are printed
+   * as "false".
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param b The <code>boolean</code> value to print
+   */
   public void println (boolean bool)
   {
     print(String.valueOf(bool), true);
   }
 
+  /**
+   * This method prints an integer to the stream.  The value printed is
+   * determined using the <code>String.valueOf()</code> method.
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param inum The <code>int</code> value to be printed
+   */
   public void println (int inum)
   {
     print(String.valueOf(inum), true);
   }
 
+  /**
+   * This method prints a long to the stream.  The value printed is
+   * determined using the <code>String.valueOf()</code> method.
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param lnum The <code>long</code> value to be printed
+   */
   public void println (long lnum)
   {
     print(String.valueOf(lnum), true);
   }
 
+  /**
+   * This method prints a float to the stream.  The value printed is
+   * determined using the <code>String.valueOf()</code> method.
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param fnum The <code>float</code> value to be printed
+   */
   public void println (float fnum)
   {
     print(String.valueOf(fnum), true);
   }
 
+  /**
+   * This method prints a double to the stream.  The value printed is
+   * determined using the <code>String.valueOf()</code> method.
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param dnum The <code>double</code> value to be printed
+   */
   public void println (double dnum)
   {
     print(String.valueOf(dnum), true);
   }
 
+  /**
+   * This method prints an <code>Object</code> to the stream.  The actual
+   * value printed is determined by calling the <code>String.valueOf()</code>
+   * method.
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param obj The <code>Object</code> to print.
+   */
   public void println (Object obj)
   {
     print(obj == null ? "null" : obj.toString(), true);
   }
 
+  /**
+   * This method prints a <code>String</code> to the stream.  The actual
+   * value printed depends on the system default encoding.
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param str The <code>String</code> to print.
+   */
   public void println (String str)
   {
     print (str == null ? "null" : str, true);
   }
 
+  /**
+   * This method prints a char to the stream.  The actual value printed is
+   * determined by the character encoding in use.
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param ch The <code>char</code> value to be printed
+   */
   public synchronized void println (char ch)
   {
     work[0] = ch;
     print(work, 0, 1, true);
   }
 
+  /**
+   * This method prints an array of characters to the stream.  The actual
+   * value printed depends on the system default encoding.
+   * <p>
+   * This method prints a line termination sequence after printing the value.
+   *
+   * @param s The array of characters to print.
+   */
   public void println (char[] charArray)
   {
     print(charArray, 0, charArray.length, true);
   }
 
+  /**
+   * This method writes a byte of data to the stream.  If auto-flush is
+   * enabled, printing a newline character will cause the stream to be
+   * flushed after the character is written.
+   * 
+   * @param b The byte to be written
+   */
   public void write (int oneByte)
   {
     try
@@ -325,11 +515,20 @@ public class PrintStream extends FilterOutputStream
       }
   }
 
-  public void write (byte[] buffer, int offset, int count)
+  /**
+   * This method writes <code>len</code> bytes from the specified array
+   * starting at index <code>offset</code> into the array.
+   *
+   * @param buffer The array of bytes to write
+   * @param offset The index into the array to start writing from
+   * @param len The number of bytes to write
+   */
+  public void write (byte[] buffer, int offset, int len)
   {
     try
       {
-	out.write(buffer, offset, count);
+	out.write (buffer, offset, len);
+        
 	if (auto_flush)
 	  flush();
       }
@@ -343,4 +542,5 @@ public class PrintStream extends FilterOutputStream
       }
   }
 
-}
+} // class PrintStream
+
diff --git a/libjava/java/io/RandomAccessFile.java b/libjava/java/io/RandomAccessFile.java
index afe54a6..990b2dc 100644
--- a/libjava/java/io/RandomAccessFile.java
+++ b/libjava/java/io/RandomAccessFile.java
@@ -525,100 +525,391 @@ public class RandomAccessFile implements DataOutput, DataInput
     return in.readLong();
   }
 
+  /**
+   * This method reads a signed 16-bit value into a Java in from the stream.
+   * It operates by reading two bytes from the stream and converting them to 
+   * a single 16-bit Java <code>short</code>  The two bytes are stored most
+   * significant byte first (i.e., "big endian") regardless of the native
+   * host byte ordering. 
+   * <p>
+   * As an example, if <code>byte1</code> and code{byte2</code> 
+   * represent the 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 & 0xFF) << 8) | (byte2 & 0xFF)</code>
+   * <p>
+   * The value returned is in the range of -32768 to 32767.
+   * <p>
+   * This method can read a <code>short</code> written by an object 
+   * implementing the
+   * <code>writeShort()</code> method in the <code>DataOutput</code> interface.
+   *
+   * @return The <code>short</code> value read
+   *
+   * @exception EOFException If end of file is reached before reading the value
+   * @exception IOException If any other error occurs
+   *
+   * @see DataOutput
+   */
   public final short readShort () throws IOException
   {
     return in.readShort();
   }
 
+  /**
+   * This method reads 8 unsigned bits into a Java <code>int</code> value 
+   * from the 
+   * stream. The value returned is in the range of 0 to 255.
+   * <p>
+   * This method can read an unsigned byte written by an object implementing 
+   * the <code>writeUnsignedByte()</code> method in the 
+   * <code>DataOutput</code> interface.
+   *
+   * @return The unsigned bytes value read as a Java <code>int</code>
+   *
+   * @exception EOFException If end of file is reached before reading the value
+   * @exception IOException If any other error occurs
+   *
+   * @see DataOutput
+   */
   public final int readUnsignedByte () throws IOException
   {
     return in.readUnsignedByte();
   }
 
+  /**
+   * This method reads 16 unsigned bits into a Java int value from the stream.
+   * It operates by reading two bytes from the stream and converting them to 
+   * a single Java <code>int</code>  The two bytes are stored most
+   * significant byte first (i.e., "big endian") regardless of the native
+   * host byte ordering. 
+   * <p>
+   * As an example, if <code>byte1</code> and <code>byte2</code> 
+   * represent the 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 & 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 
+   * <code>DataOutput</code> interface.
+   *
+   * @return The unsigned short value read as a Java <code>int</code>
+   *
+   * @exception EOFException If end of file is reached before reading the value
+   * @exception IOException If any other error occurs
+   */
   public final int readUnsignedShort () throws IOException
   {
     return in.readUnsignedShort();
   }
 
+  /**
+   * This method reads a <code>String</code> from an input stream that 
+   * is encoded in
+   * a modified UTF-8 format.  This format has a leading two byte sequence
+   * that contains the remaining number of bytes to read.  This two byte
+   * sequence is read using the <code>readUnsignedShort()</code> method of this
+   * interface.
+   * <p>
+   * After the number of remaining bytes have been determined, these bytes
+   * are read an transformed into <code>char</code> values.  
+   * These <code>char</code> values
+   * are encoded in the stream using either a one, two, or three byte format.
+   * The particular format in use can be determined by examining the first
+   * byte read.  
+   * <p>
+   * If the first byte has a high order bit of 0 then
+   * that character consists on only one byte.  This character value consists
+   * of seven bits that are at positions 0 through 6 of the byte.  As an
+   * example, if <code>byte1</code> is the byte read from the stream, it would
+   * be converted to a <code>char</code> like so:
+   * <p>
+   * <code>(char)byte1</code>
+   * <p>
+   * If the first byte has <code>110</code> as its high order bits, then the 
+   * character consists of two bytes.  The bits that make up the character
+   * value are in positions 0 through 4 of the first byte and bit positions
+   * 0 through 5 of the second byte.  (The second byte should have 
+   * 10 as its high order bits).  These values are in most significant
+   * byte first (i.e., "big endian") order.
+   * <p>
+   * As an example, if <code>byte1</code> and <code>byte2</code> 
+   * are the first two bytes
+   * read respectively, and the high order bits of them match the patterns
+   * which indicate a two byte character encoding, then they would be
+   * converted to a Java <code>char</code> like so:
+   * <p>
+   * <code>(char)(((byte1 & 0x1F) << 6) | (byte2 & 0x3F))</code>
+   * <p>
+   * If the first byte has a <code>1110</code> as its high order bits, then the
+   * character consists of three bytes.  The bits that make up the character
+   * value are in positions 0 through 3 of the first byte and bit positions
+   * 0 through 5 of the other two bytes.  (The second and third bytes should
+   * have <code>10</code> as their high order bits).  These values are in most
+   * significant byte first (i.e., "big endian") order.
+   * <p>
+   * As an example, if <code>byte1</code> <code>byte2</code> 
+   * and <code>byte3</code> are the
+   * three bytes read, and the high order bits of them match the patterns
+   * which indicate a three byte character encoding, then they would be
+   * converted to a Java <code>char</code> like so:
+   * <p>
+   * <code>(char)(((byte1 & 0x0F) << 12) | ((byte2 & 0x3F) << 6) | 
+   * (byte3 & 0x3F))</code>
+   * <p>
+   * Note that all characters are encoded in the method that requires the
+   * fewest number of bytes with the exception of the character with the
+   * value of <code>&#92;u0000</code> which is encoded as two bytes.  This is 
+   * a  modification of the UTF standard used to prevent C language style
+   * <code>NUL</code> values from appearing in the byte stream.
+   * <p>
+   * This method can read data that was written by an object implementing the
+   * <code>writeUTF()</code> method in <code>DataOutput</code>
+   * 
+   * @return The <code>String</code> read
+   *
+   * @exception EOFException If end of file is reached before reading the 
+   * String
+   * @exception UTFDataFormatException If the data is not in UTF-8 format
+   * @exception IOException If any other error occurs
+   *
+   * @see DataOutput
+   */
   public final String readUTF () throws IOException
   {
     return in.readUTF();
   }
 
+  /**
+   * This method sets the current file position to the specified offset 
+   * from the beginning of the file.  Note that some operating systems will
+   * allow the file pointer to be set past the current end of the file.
+   *
+   * @param pos The offset from the beginning of the file at which to set 
+   * the file pointer
+   *
+   * @exception IOException If an error occurs
+   */
   public void seek (long pos) throws IOException
   {
-    fd.seek(pos, FileDescriptor.SET, false);
+    fd.seek (pos, FileDescriptor.SET, false);
   }
 
-  public int skipBytes (int count) throws IOException
+  /**
+   * This method attempts to skip and discard the specified number of bytes 
+   * in the input stream.  It may actually skip fewer bytes than requested. 
+   * The actual number of bytes skipped is returned.  This method will not
+   * skip any bytes if passed a negative number of bytes to skip.
+   *
+   * @param numBytes The requested number of bytes to skip.
+   *
+   * @return The number of bytes actually skipped.
+   *
+   * @exception IOException If an error occurs.
+   */
+  public int skipBytes (int numBytes) throws IOException
   {
-    if (count <= 0)
+    if (numBytes < 0)
+      throw new IllegalArgumentException ("Can't skip negative bytes: " +
+                                          numBytes);
+    
+    if (numBytes == 0)
       return 0;
-    long startPos = fd.getFilePointer();
-    long endPos = fd.seek(count, FileDescriptor.CUR, true);
-    return (int) (endPos - startPos);
+    
+    long curPos = fd.getFilePointer ();
+    long newPos = fd.seek (numBytes, FileDescriptor.CUR, true);
+    
+    return (int) (newPos - curPos);
   }
 
+  /**
+   * This method writes a single byte of data to the file. The file must
+   * be open for read-write in order for this operation to succeed.
+   *
+   * @param The byte of data to write, passed as an int.
+   *
+   * @exception IOException If an error occurs
+   */
   public void write (int oneByte) throws IOException
   {
     out.write(oneByte);
   }
 
+  /**
+   * This method writes all the bytes in the specified array to the file.
+   * The file must be open read-write in order for this operation to succeed.
+   *
+   * @param buf The array of bytes to write to the file
+   */
   public void write (byte[] buffer) throws IOException
   {
     out.write(buffer);
   }
 
-  public void write (byte[] buffer, int offset, int count) throws IOException
+  /**
+   * This method writes <code>len</code> bytes to the file from the specified
+   * array starting at index <code>offset</code> into the array.
+   *
+   * @param buf The array of bytes to write to the file
+   * @param offset The index into the array to start writing file
+   * @param len The number of bytes to write
+   *
+   * @exception IOException If an error occurs
+   */
+  public void write (byte[] buffer, int offset, int len) throws IOException
   {
-    out.write(buffer, offset, count);
+    out.write (buffer, offset, len);
   }
 
+  /**
+   * 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.
+   *
+   * @param b The <code>boolean</code> value to write to the stream
+   *
+   * @exception IOException If an error occurs
+   */
   public final void writeBoolean (boolean val) throws IOException
   {
     out.writeBoolean(val);
   }
 
+  /**
+   * This method writes a Java <code>byte</code> value to the underlying
+   * output stream.
+   *
+   * @param b The <code>byte</code> to write to the stream, passed 
+   * as an <code>int</code>.
+   *
+   * @exception IOException If an error occurs
+   */
   public final void writeByte (int v) throws IOException
   {
     out.writeByte(v);
   }
 
+  /**
+   * This method writes a Java <code>short</code> to the stream, high byte
+   * first.  This method requires two bytes to encode the value.
+   *
+   * @param s The <code>short</code> value to write to the stream, 
+   * passed as an <code>int</code>.
+   *
+   * @exception IOException If an error occurs
+   */
   public final void writeShort (int v) throws IOException
   {
     out.writeShort(v);
   }
 
+  /**
+   * This method writes a single <code>char</code> value to the stream,
+   * high byte first.
+   *
+   * @param v The <code>char</code> value to write, passed as 
+   * an <code>int</code>.
+   *
+   * @exception IOException If an error occurs
+   */
   public final void writeChar (int v) throws IOException
   {
     out.writeChar(v);
   }
 
+  /**
+   * This method writes a Java <code>int</code> to the stream, high bytes
+   * first.  This method requires four bytes to encode the value.
+   *
+   * @param v The <code>int</code> value to write to the stream.
+   *
+   * @exception IOException If an error occurs
+   */
   public final void writeInt (int v) throws IOException
   {
     out.writeInt(v);
   }
 
+  /**
+   * This method writes a Java <code>long</code> to the stream, high bytes
+   * first.  This method requires eight bytes to encode the value.
+   *
+   * @param v The <code>long</code> value to write to the stream.
+   *
+   * @exception IOException If an error occurs
+   */
   public final void writeLong (long v) throws IOException
   {
     out.writeLong(v);
   }
 
+  /**
+   * 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.
+   *
+   * @param v The floating point number to write to the stream.
+   *
+   * @exception IOException If an error occurs
+   *
+   * @see #writeInt(int)
+   */
   public final void writeFloat (float v) throws IOException
   {
     out.writeFloat(v);
   }
 
+  /**
+   * 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.
+   *
+   * @param v The double precision floating point number to write to the 
+   * stream.
+   *
+   * @exception IOException If an error occurs
+   *
+   * @see #writeLong(long)
+   */
   public final void writeDouble (double v) throws IOException
   {
     out.writeDouble(v);
   }
 
+  /**
+   * 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.
+   *
+   * @param s The <code>String</code> to write to the stream
+   *
+   * @exception IOException If an error occurs
+   */
   public final void writeBytes (String s) throws IOException
   {
     out.writeBytes(s);
   }
-
+  
+  /**
+   * 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.
+   *
+   * @param s The <code>String</code> to write to the stream.
+   *
+   * @exception IOException If an error occurs
+   */
   public final void writeChars (String s) throws IOException
   {
     out.writeChars(s);
@@ -653,7 +944,7 @@ public class RandomAccessFile implements DataOutput, DataInput
    *
    * @exception IOException If an error occurs
    */
-  public final void writeUTF(String s) throws IOException
+  public final void writeUTF (String s) throws IOException
   {
     out.writeUTF(s);
   }
@@ -664,7 +955,7 @@ public class RandomAccessFile implements DataOutput, DataInput
    * A file channel must be created by first creating an instance of
    * Input/Output/RandomAccessFile and invoking the getChannel() method on it.
    */
-  public synchronized FileChannel getChannel() 
+  public synchronized FileChannel getChannel ()
   {
     if (ch == null)
       ch = new FileChannelImpl (fd, true, this);