DataInputStream.java (): Wrapped documentation line.

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

	* java/io/DataInputStream.java
	(): Wrapped documentation line.
	(): Fixed @return tag.
	* java/io/DataOutputStream.java
	(written): Moved to top of class.
	(all methods): Merged documentation from classpath.
	* java/io/File.java:
	Merged copyright year with classpath.
	* java/io/FileInputStream.java
	(all methods): Merged documentation from classpath.
	* java/io/LineNumberReader.java
	(getLineNumber): Fixed @return tag.
	* java/io/ObjectInputStream.java.
	Reformatted.
	* java/io/ObjectOutputStream.java:
	Reformatted, fixed some @see tags.
	* java/io/OutputStreamWriter.java:
	Deleted empty line.
	* java/io/Writer.java:
	Reformatted.

From-SVN: r64780

libjava/ChangeLog

 2003-03-24  Michael Koch  <konqueror@gmx.de>
 
+	* java/io/DataInputStream.java
+	(): Wrapped documentation line.
+	(): Fixed @return tag.
+	* java/io/DataOutputStream.java
+	(written): Moved to top of class.
+	(all methods): Merged documentation from classpath.
+	* java/io/File.java:
+	Merged copyright year with classpath.
+	* java/io/FileInputStream.java
+	(all methods): Merged documentation from classpath.
+	* java/io/LineNumberReader.java
+	(getLineNumber): Fixed @return tag.
+	* java/io/ObjectInputStream.java.
+	Reformatted.
+	* java/io/ObjectOutputStream.java:
+	Reformatted, fixed some @see tags.
+	* java/io/OutputStreamWriter.java:
+	Deleted empty line.
+	* java/io/Writer.java:
+	Reformatted.
+
+2003-03-24  Michael Koch  <konqueror@gmx.de>
+
 	* java/awt/Frame.java
 	(DEFAULT_CURSOR): Fixed @deprecated tag.
 	(setCursor): Fixed @deprecated tag.

libjava/java/io/DataInputStream.java

@@ -596,7 +596,8 @@ public class DataInputStream extends FilterInputStream implements DataInput
    * 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>
+   * <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
@@ -608,7 +609,7 @@ public class DataInputStream extends FilterInputStream implements DataInput
    * This method can read data that was written by an object implementing the
    * <code>writeUTF()</code> method in <code>DataOutput</code>
    * 
-   * @returns The <code>String</code> read
+   * @return The <code>String</code> read
    *
    * @exception EOFException If end of file is reached before reading
    * the String

libjava/java/io/File.java

 /* File.java -- Class representing a file on disk
-   Copyright (C) 1998, 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2003 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 

libjava/java/io/FileInputStream.java

@@ -3,6 +3,11 @@
 
 This file is part of GNU Classpath.
 
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+ 
 GNU Classpath is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
@@ -36,23 +41,43 @@ package java.io;
 import java.nio.channels.FileChannel;
 import gnu.java.nio.FileChannelImpl;
 
-/**
- * @author Warren Levy <warrenl@cygnus.com>
- * @date October 28, 1998.  
- */
 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
  * "The Java Language Specification", ISBN 0-201-63451-1
  * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
  * Status:  Believed complete and correct.
  */
  
+/**
+ * This class is a stream that reads its bytes from a file. 
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @date October 28, 1998.  
+ */
 public class FileInputStream extends InputStream
 {
-  /* Contains the file descriptor for referencing the actual file. */
+  /**
+   * This is the native file handle for the file this stream is reading from
+   */
   private FileDescriptor fd;
 
-  private FileChannel ch;
+  private FileChannel ch;  /* cached associated file-channel */
 
+  /**
+   * This method initializes a <code>FileInputStream</code> to read from the
+   * specified named file.  A security check is first made to determine
+   * whether or not access to this file is allowed.  This is done by
+   * calling the <code>checkRead()</code> method of the 
+   * <code>SecurityManager</code>
+   * (if one exists) with the name of this file.  An exception is thrown
+   * if reading is not allowed.  If the file does not exist, an exception
+   * is also thrown.
+   *
+   * @param name The name of the file this stream should read from
+   *
+   * @exception SecurityException If read access to the file is not allowed
+   * @exception FileNotFoundException If the file does not exist.
+   */
   public FileInputStream(String name) throws FileNotFoundException
   {
     SecurityManager s = System.getSecurityManager();
@@ -61,24 +86,83 @@ public class FileInputStream extends InputStream
     fd = new FileDescriptor(name, FileDescriptor.READ);
   }
 
+  /**
+   * This method initializes a <code>FileInputStream</code> to read from the
+   * specified <code>File</code> object.  A security check is first
+   * made to determine
+   * whether or not access to this file is allowed.  This is done by
+   * calling the <code>checkRead()</code> method of the
+   * <code>SecurityManager</code>
+   * (if one exists) with the name of this file.  An exception is thrown
+   * if reading is not allowed.  If the file does not exist, an exception
+   * is also thrown.
+   *
+   * @param file The <code>File</code> object this stream should read from
+   *
+   * @exception SecurityException If read access to the file is not allowed
+   * @exception FileNotFoundException If the file does not exist.
+   */
   public FileInputStream(File file) throws FileNotFoundException
   {
     this(file.getPath());
   }
 
+  /**
+   * This method initializes a <code>FileInputStream</code> to read from the
+   * specified <code>FileDescriptor</code> object.  A security
+   * check is first made to
+   * determine whether or not access to this file is allowed.  This is done by
+   * calling the <code>checkRead()</code> method of the 
+   * <code>SecurityManager</code>
+   * (if one exists) with the specified <code>FileDescriptor</code>  
+   * An exception is 
+   * thrown if reading is not allowed.
+   *
+   * @param fd The <code>FileDescriptor</code> object this stream 
+   * should read from
+   *
+   * @exception SecurityException If read access to the file is not allowed
+   */
   public FileInputStream(FileDescriptor fdObj)
   {
     SecurityManager s = System.getSecurityManager();
     if (s != null)
       s.checkRead(fdObj);
+
     fd = fdObj;
   }
 
+  /**
+   * This method returns the number of bytes that can be read from this
+   * stream before a read can block.  A return of 0 indicates that blocking
+   * might (or might not) occur on the very next read attempt.
+   * <p>
+   * This method returns the number of unread bytes remaining in the file if
+   * the descriptor being read from is an actual file.  If this method is
+   * reading from a ''special'' file such a the standard input, this method
+   * will return the appropriate value for the stream being read.
+   * <p>
+   * Be aware that reads on plain files that do not reside locally might
+   * possibly block even if this method says they should not.  For example,
+   * a remote server might crash, preventing an NFS mounted file from being
+   * read.
+   *
+   * @return The number of bytes that can be read before blocking could occur
+   *
+   * @exception IOException If an error occurs
+   */
   public int available() throws IOException
   {
     return fd.available();
   }
 
+  /**
+   * This method closes the stream.  Any futher attempts to read from the
+   * stream will likely generate an IOException since the underlying file
+   * will be closed.
+   *
+   * @exception IOException If an error occurs.
+   */
   public void close() throws IOException
   {
     if (fd.valid())
@@ -91,6 +175,15 @@ public class FileInputStream extends InputStream
     // mentioned in the JCL.
   }
 
+  /**
+   * This method returns a <code>FileDescriptor</code> object representing the
+   * underlying native file handle of the file this stream is reading
+   * from
+   *
+   * @return A <code>FileDescriptor</code> for this stream
+   *
+   * @exception IOException If an error occurs
+   */
   public final FileDescriptor getFD() throws IOException
   {
     if (!fd.valid())
@@ -98,16 +191,63 @@ public class FileInputStream extends InputStream
     return fd;
   }
 
+  /**
+   * This method reads an unsigned byte from the input stream and returns it
+   * as an int in the range of 0-255.  This method also will return -1 if
+   * the end of the stream has been reached.
+   * <p>
+   * This method will block until the byte can be read.
+   *
+   * @return The byte read or -1 if end of stream
+   *
+   * @exception IOException If an error occurs
+   */
   public int read() throws IOException
   {
     return fd.read();
   }
 
+  /**
+   * This method reads bytes from a stream and stores them into a caller
+   * supplied buffer.  This method attempts to completely fill the buffer,
+   * but can return before doing so.  The actual number of bytes read is
+   * returned as an int.  A -1 is returned to indicate the end of the stream.
+   * <p>
+   * This method will block until some data can be read.
+   * <p>
+   * This method operates by calling an overloaded read method like so:
+   * <code>read(buf, 0, buf.length)</code>
+   *
+   * @param buf The buffer into which the bytes read will be stored.
+   *
+   * @return The number of bytes read or -1 if end of stream.
+   *
+   * @exception IOException If an error occurs.
+   */
   public int read(byte[] b) throws IOException
   {
     return fd.read(b, 0, b.length);
   }
 
+  /**
+   * This method read bytes from a stream and stores them into a caller
+   * supplied buffer.  It starts storing the data at index 
+   * <code>offset</code> into
+   * the buffer and attempts to read <code>len</code> bytes.  This method can
+   * return before reading the number of bytes requested.  The actual number
+   * of bytes read is returned as an int.  A -1 is returned to indicate the
+   * end of the stream.
+   * <p>
+   * This method will block until some data can be read.
+   *
+   * @param buf The array into which the bytes read should be stored
+   * @param offset The offset into the array to start storing bytes
+   * @param len The requested number of bytes to read
+   *
+   * @return The actual number of bytes read, or -1 if end of stream.
+   *
+   * @exception IOException If an error occurs.
+   */
   public int read(byte[] b, int off, int len) throws IOException
   {
     if (off < 0 || len < 0 || off + len > b.length)
@@ -116,6 +256,17 @@ public class FileInputStream extends InputStream
     return fd.read(b, off, len);
   }
 
+  /**
+   * This method skips the specified number of bytes in the stream.  It
+   * returns the actual number of bytes skipped, which may be less than the
+   * requested amount.
+   * <p>
+   * @param numBytes The requested number of bytes to skip
+   *
+   * @return The actual number of bytes skipped.
+   *
+   * @exception IOException If an error occurs
+   */
   public long skip(long n) throws IOException
   {
     long startPos = fd.getFilePointer();
@@ -123,6 +274,12 @@ public class FileInputStream extends InputStream
     return endPos - startPos;
   }
 
+  /**
+   * This method creates a java.nio.channels.FileChannel.
+   * Nio does not allow one to create a file channel directly.
+   * A file channel must be created by first creating an instance of
+   * Input/Output/RandomAccessFile and invoking the getChannel() method on it.
+   */
   public FileChannel getChannel ()
   {
     synchronized (this)
@@ -133,4 +290,6 @@ public class FileInputStream extends InputStream
         return ch;
       }
   }
-}
+
+} // class FileInputStream
+

libjava/java/io/LineNumberReader.java

@@ -100,7 +100,7 @@ public class LineNumberReader extends BufferedReader
   /**
     * This method returns the current line number
     *
-    * @returns The current line number
+    * @return The current line number
     */
   public int getLineNumber()
   {

libjava/java/io/OutputStreamWriter.java

@@ -47,7 +47,6 @@ import gnu.gcj.convert.UnicodeToBytes;
  * API docs for JDK 1.2 beta from http://www.javasoft.com.
  * Status:  Believed complete and correct, but only supports 8859_1.
  */
-
 public class OutputStreamWriter extends Writer
 {
   BufferedOutputStream out;

libjava/java/io/Writer.java

@@ -44,93 +44,75 @@ package java.io;
  */
 
 /**
-  * This abstract class forms the base of the hierarchy of classes that 
-  * write output as a stream of chars.  It provides a common set of methods
-  * for writing chars to stream.  Subclasses implement and/or extend these
-  * methods to write chars in a particular manner or to a particular 
-  * destination such as a file on disk or network connection.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  * @author Per Bothner <bothner@cygnus.com>
-  */
+ * This abstract class forms the base of the hierarchy of classes that 
+ * write output as a stream of chars.  It provides a common set of methods
+ * for writing chars to stream.  Subclasses implement and/or extend these
+ * methods to write chars in a particular manner or to a particular 
+ * destination such as a file on disk or network connection.
+ *
+ * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Per Bothner <bothner@cygnus.com>
+ */
 public abstract class Writer
 {
   /**
-    * This is the object used to synchronize criticial code sections for
-    * thread safety.  Subclasses should use this field instead of using
-    * synchronized methods or explicity synchronizations on <code>this</code>
-    */
-  protected Object lock;
-
-  /*************************************************************************/
-
-  /*
-   * Constructors
+   * This is the object used to synchronize criticial code sections for
+   * thread safety.  Subclasses should use this field instead of using
+   * synchronized methods or explicity synchronizations on <code>this</code>
    */
+  protected Object lock;
 
   /**
-    * This is the default no-argument constructor for this class.  This method
-    * will set up the class to synchronize criticial sections on itself.
-    */
+   * This is the default no-argument constructor for this class.  This method
+   * will set up the class to synchronize criticial sections on itself.
+   */
   protected Writer()
   {
     lock = this;
   }
 
-  /*************************************************************************/
-
   /**
-    * This method initializes a <code>Writer</code> that will synchronize
-    * on the specified <code>Object</code>.
-    *
-    * @param obj The <code>Object</code> to use for synchronizing critical
-    *            sections
-    */
+   * This method initializes a <code>Writer</code> that will synchronize
+   * on the specified <code>Object</code>.
+   *
+   * @param obj The <code>Object</code> to use for synchronizing critical
+   *            sections
+   */
   protected Writer(Object lock)
   {
     this.lock = lock;
   }
 
-  /*************************************************************************/
-
-  /*
-   * Instance Methods
-   */
-
   /**
-    * This method forces any data that may have been buffered to be written
-    * to the underlying output device.  Please note that the host environment
-    * might perform its own buffering unbeknowst to Java.  In that case, a
-    * write made (for example, to a disk drive) might be cached in OS
-    * buffers instead of actually being written to disk.
-    *
-    * @exception IOException If an error occurs
-    */
+   * This method forces any data that may have been buffered to be written
+   * to the underlying output device.  Please note that the host environment
+   * might perform its own buffering unbeknowst to Java.  In that case, a
+   * write made (for example, to a disk drive) might be cached in OS
+   * buffers instead of actually being written to disk.
+   *
+   * @exception IOException If an error occurs
+   */
   public abstract void flush() throws IOException;
 
-  /*************************************************************************/
-
   /**
-    * This method closes the stream.  Any internal or native resources 
-    * associated
-    * with this stream are freed.  Any subsequent attempt to access the stream
-    * might throw an exception.
-    * <p>
-    * This method in this class does nothing.
-    *
-    * @exception IOException If an error occurs
-    */
+   * This method closes the stream.  Any internal or native resources 
+   * associated
+   * with this stream are freed.  Any subsequent attempt to access the stream
+   * might throw an exception.
+   * <p>
+   * This method in this class does nothing.
+   *
+   * @exception IOException If an error occurs
+   */
   public abstract void close() throws IOException;
 
-  /*************************************************************************/
-
   /**
-    * This method writes a single char to the output stream. 
-    *
-    * @param b The char to be written to the output stream, passed as an int
-    *
-    * @exception IOException If an error occurs
-    */
+   * This method writes a single char to the output stream. 
+   *
+   * @param b The char to be written to the output stream, passed as an int
+   *
+   * @exception IOException If an error occurs
+   */
   public void write(int b) throws IOException
   {
     char[] buf = new char[1];
@@ -139,68 +121,60 @@ public abstract class Writer
     write(buf, 0, buf.length);
   }
 
-  /*************************************************************************/
-
   /**
-    * This method all the writes char from the passed array to the output 
-    * stream. This method is equivalent to 
-    * <code>write(buf, 0, buf.length)</code> which
-    * is exactly how it is implemented in this class.
-    *
-    * @param buf The array of char to write
-    *
-    * @exception IOException If an error occurs
-    */
+   * This method all the writes char from the passed array to the output 
+   * stream. This method is equivalent to 
+   * <code>write(buf, 0, buf.length)</code> which
+   * is exactly how it is implemented in this class.
+   *
+   * @param buf The array of char to write
+   *
+   * @exception IOException If an error occurs
+   */
   public void write(char[] buf) throws IOException
   {
     write(buf, 0, buf.length);
   }
 
-  /*************************************************************************/
-
   /**
-    * This method writes <code>len</code> char from the specified array
-    * <code>buf</code> starting at index <code>offset</code> into the array.
-    * <p>
-    * Subclasses must provide an implementation of this abstract method.
-    *
-    * @param buf The array of char to write from
-    * @param offset The index into the array to start writing from
-    * @param len The number of char to write
-    * 
-    * @exception IOException If an error occurs
-    */
+   * This method writes <code>len</code> char from the specified array
+   * <code>buf</code> starting at index <code>offset</code> into the array.
+   * <p>
+   * Subclasses must provide an implementation of this abstract method.
+   *
+   * @param buf The array of char to write from
+   * @param offset The index into the array to start writing from
+   * @param len The number of char to write
+   * 
+   * @exception IOException If an error occurs
+   */
   public abstract void write(char[] buf, int offset, int len) 
     throws IOException;
 
-  /*************************************************************************/
-
   /**
-    * This method writes all the characters in a <code>String</code> to the
-    * output.
-    *
-    * @param str The <code>String</code> whose chars are to be written.
-    *
-    * @param IOException If an error occurs
-    */
+   * This method writes all the characters in a <code>String</code> to the
+   * output.
+   *
+   * @param str The <code>String</code> whose chars are to be written.
+   *
+   * @param IOException If an error occurs
+   */
   public void write(String str) throws IOException
   {
     write(str, 0, str.length());
   } 
 
-  /*************************************************************************/
-
   /**
-    * This method writes <code>len</code> chars from the <code>String</code>
-    * starting at position <code>offset</code>.
-    *
-    * @param str The <code>String</code> that is to be written
-    * @param offset The character offset into the <code>String</code> to start
-    *               writing from
-    * @param len The number of chars to write
-    *
-    * @exception IOException If an error occurs
-    */
+   * This method writes <code>len</code> chars from the <code>String</code>
+   * starting at position <code>offset</code>.
+   *
+   * @param str The <code>String</code> that is to be written
+   * @param offset The character offset into the <code>String</code> 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
   {
     // FIXME - for libgcj re-write using native code to not require