2004-04-08 Michael Koch <konqueror@gmx.de>

	* java/io/ByteArrayInputStream.java,
	java/io/DataInput.java,
	java/io/DataInputStream.java,
	java/io/InputStream.java,
	java/io/InputStreamReader.java,
	java/io/ObjectStreamClass.java,
	java/io/ObjectStreamField.java,
	java/io/PushbackReader.java,
	java/io/StringWriter.java,
	java/io/Writer.java:
	Fixed javadocs and style all over.

10 files changed, 68 insertions, 54 deletions

diff --git a/java/io/ByteArrayInputStream.java b/java/io/ByteArrayInputStream.java
index 6a5f2c618..45a09a77b 100644
--- a/java/io/ByteArrayInputStream.java
+++ b/java/io/ByteArrayInputStream.java
@@ -83,7 +83,7 @@ public class ByteArrayInputStream extends InputStream
    * bytes supplied to the reader.  Please use caution in changing the 
    * contents of the buffer while this stream is open.
    *
-   * @param buf The byte array buffer this stream will read from.
+   * @param buffer The byte array buffer this stream will read from.
    */
   public ByteArrayInputStream(byte[] buffer)
   {
@@ -105,7 +105,7 @@ public class ByteArrayInputStream extends InputStream
    * bytes supplied to the reader.  Please use caution in changing the 
    * contents of the buffer while this stream is open.
    *
-   * @param buf The byte array buffer this stream will read from.
+   * @param buffer The byte array buffer this stream will read from.
    * @param offset The index into the buffer to start reading bytes from
    * @param length The number of bytes to read from the buffer
    */
@@ -146,12 +146,12 @@ public class ByteArrayInputStream extends InputStream
    * position 0 in the stream.  This is in constrast to some other
    * stream types where there is no default mark position.
    *
-   * @param readlimit The number of bytes this stream must remember.
+   * @param readLimit The number of bytes this stream must remember.
    * This parameter is ignored.
    */
-  public synchronized void mark(int readAheadLimit)
+  public synchronized void mark(int readLimit)
   {
-    // readAheadLimit is ignored per Java Class Lib. book, p.220.
+    // readLimit is ignored per Java Class Lib. book, p.220.
     mark = pos;
   }
 
@@ -197,19 +197,19 @@ public class ByteArrayInputStream extends InputStream
    * <p>
    * This method does not block.
    *
-   * @param buf The array into which the bytes read should be stored.
+   * @param buffer 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
+   * @param length The requested number of bytes to read
    *
    * @return The actual number of bytes read, or -1 if end of stream.
    */
-  public synchronized int read(byte[] b, int off, int len)
+  public synchronized int read(byte[] buffer, int offset, int length)
   {
     if (pos >= count)
       return -1;
 
-    int numBytes = Math.min(count - pos, len);
-    System.arraycopy(buf, pos, b, off, numBytes);
+    int numBytes = Math.min(count - pos, length);
+    System.arraycopy(buf, pos, buffer, offset, numBytes);
     pos += numBytes;
     return numBytes;
   }
@@ -234,17 +234,17 @@ public class ByteArrayInputStream extends InputStream
    * position the stream at the end of the buffer.  The actual number
    * of bytes skipped is returned.
    *
-   * @param num_bytes The requested number of bytes to skip
+   * @param num The requested number of bytes to skip
    *
    * @return The actual number of bytes skipped.
    */
-  public synchronized long skip(long n)
+  public synchronized long skip(long num)
   {
     // Even though the var numBytes is a long, in reality it can never
     // be larger than an int since the result of subtracting 2 positive
     // ints will always fit in an int.  Since we have to return a long
     // anyway, numBytes might as well just be a long.
-    long numBytes = Math.min((long) (count - pos), n < 0 ? 0L : n);
+    long numBytes = Math.min((long) (count - pos), num < 0 ? 0L : num);
     pos += numBytes;
     return numBytes;
   }
diff --git a/java/io/DataInput.java b/java/io/DataInput.java
index 2d9200661..b6e725402 100644
--- a/java/io/DataInput.java
+++ b/java/io/DataInput.java
@@ -360,7 +360,7 @@ public interface DataInput
    * 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>
+   * <code>(char)(((byte1 &amp; 0x1F) &lt;&lt; 6) + (byte2 &amp; 0x3F))</code>
    * <p>
    * If the first byte has a 1110 as its high order bits, then the
    * character consists of three bytes.  The bits that make up the character
@@ -375,7 +375,7 @@ public interface DataInput
    * then they would be converted to a Java <code>char</code> like so:
    *
    * <code>
-   * (char)(((byte1 & 0x0F) << 12) + ((byte2 & 0x3F) + (byte3 & 0x3F))
+   * (char)(((byte1 &amp; 0x0F) &lt;&lt; 12) + ((byte2 &amp; 0x3F) + (byte3 &amp; 0x3F))
    * </code>
    *
    * Note that all characters are encoded in the method that requires the
@@ -387,7 +387,7 @@ public interface 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
diff --git a/java/io/DataInputStream.java b/java/io/DataInputStream.java
index 6b4b1d74e..b33cbe756 100644
--- a/java/io/DataInputStream.java
+++ b/java/io/DataInputStream.java
@@ -277,16 +277,16 @@ public class DataInputStream extends FilterInputStream implements DataInput
    * buffer
    * @exception IOException If any other error occurs
    */
-  public final void readFully (byte[] b, int off, int len) throws IOException
+  public final void readFully (byte[] buf, int offset, int len) throws IOException
   {
     while (len > 0)
       {
 	// in.read will block until some data is available.
-	int numread = in.read (b, off, len);
+	int numread = in.read (buf, offset, len);
 	if (numread < 0)
 	  throw new EOFException ();
 	len -= numread;
-	off += numread;
+	offset += numread;
       }
   }
 
diff --git a/java/io/InputStream.java b/java/io/InputStream.java
index 34068c628..264d2f1ff 100644
--- a/java/io/InputStream.java
+++ b/java/io/InputStream.java
@@ -105,7 +105,7 @@ public abstract class InputStream
    * @param readLimit The number of bytes that can be read before the
    *                  mark becomes invalid
    */
-  public void mark(int readlimit)
+  public void mark(int readLimit)
   {
     // Do nothing
   }
diff --git a/java/io/InputStreamReader.java b/java/io/InputStreamReader.java
index b0d17f11d..09fcf12e5 100644
--- a/java/io/InputStreamReader.java
+++ b/java/io/InputStreamReader.java
@@ -150,7 +150,7 @@ public class InputStreamReader extends Reader
    * by this object.  If the stream has been closed, this method is allowed
    * to return <code>null</code>.
    *
-   * @param The current encoding name
+   * @return The current encoding name
    */
   public String getEncoding()
   {
@@ -217,7 +217,7 @@ public class InputStreamReader extends Reader
     * returns the actual number of chars skipped, which may be less than the
     * requested amount.
     *
-    * @param num_chars The requested number of chars to skip
+    * @param count The requested number of chars to skip
     *
     * @return The actual number of chars skipped.
     *
@@ -230,6 +230,4 @@ public class InputStreamReader extends Reader
      
      return super.skip(count);
   }
-
-} // class InputStreamReader
-
+}
diff --git a/java/io/ObjectStreamClass.java b/java/io/ObjectStreamClass.java
index d080f280b..ee23f5996 100644
--- a/java/io/ObjectStreamClass.java
+++ b/java/io/ObjectStreamClass.java
@@ -104,17 +104,17 @@ public class ObjectStreamClass implements Serializable
       }
   }
 
-
   /**
    * Returns the name of the class that this
    * <code>ObjectStreamClass</code> represents.
+   *
+   * @return the name of the class.
    */
   public String getName()
   {
     return name;
   }
 
-
   /**
    * Returns the class that this <code>ObjectStreamClass</code>
    * represents.  Null could be returned if this
@@ -129,24 +129,27 @@ public class ObjectStreamClass implements Serializable
     return clazz;
   }
 
-
   /**
    * Returns the serial version stream-unique identifier for the class
    * represented by this <code>ObjectStreamClass</code>.  This SUID is
    * either defined by the class as <code>static final long
    * serialVersionUID</code> or is calculated as specified in
    * Javasoft's "Object Serialization Specification" XXX: add reference
+   *
+   * @return the serial version UID.
    */
   public long getSerialVersionUID()
   {
     return uid;
   }
 
-
-  // Returns the serializable (non-static and non-transient) Fields
-  // of the class represented by this ObjectStreamClass.  The Fields
-  // are sorted by name.
-  // XXX doc
+  /**
+   * Returns the serializable (non-static and non-transient) Fields
+   * of the class represented by this ObjectStreamClass.  The Fields
+   * are sorted by name.
+   *
+   * @return the fields.
+   */
   public ObjectStreamField[] getFields()
   {
     ObjectStreamField[] copy = new ObjectStreamField[ fields.length ];
@@ -154,7 +157,6 @@ public class ObjectStreamClass implements Serializable
     return copy;
   }
 
-
   // XXX doc
   // Can't do binary search since fields is sorted by name and
   // primitiveness.
@@ -166,7 +168,6 @@ public class ObjectStreamClass implements Serializable
     return null;
   }
 
-
   /**
    * Returns a textual representation of this
    * <code>ObjectStreamClass</code> object including the name of the
@@ -181,7 +182,6 @@ public class ObjectStreamClass implements Serializable
     return "java.io.ObjectStreamClass< " + name + ", " + uid + " >";
   }
 
-
   // Returns true iff the class that this ObjectStreamClass represents
   // has the following method:
   //
diff --git a/java/io/ObjectStreamField.java b/java/io/ObjectStreamField.java
index 901c38f03..e4f11af99 100644
--- a/java/io/ObjectStreamField.java
+++ b/java/io/ObjectStreamField.java
@@ -86,6 +86,7 @@ public class ObjectStreamField implements Comparable
    *
    * @param name Name of the field to export.
    * @param type Type of the field in the concerned class.
+   * @param unshared true if field will be unshared, false otherwise.
    */
   public ObjectStreamField (String name, Class type, boolean unshared)
   {
@@ -237,9 +238,16 @@ public class ObjectStreamField implements Comparable
     return typename.length() == 1;
   }
 
-  public int compareTo (Object o)
+  /**
+   * Compares this object to the given object.
+   *
+   * @param obj the object to compare to.
+   *
+   * @return -1, 0 or 1.
+   */
+  public int compareTo (Object obj)
   {
-    ObjectStreamField f = (ObjectStreamField)o;
+    ObjectStreamField f = (ObjectStreamField) obj;
     boolean this_is_primitive = isPrimitive ();
     boolean f_is_primitive = f.isPrimitive ();
 
@@ -347,6 +355,11 @@ public class ObjectStreamField implements Comparable
 	 " in class " + field.getDeclaringClass());
   }
 
+  /**
+   * Returns a string representing this object.
+   *
+   * @return the string.
+   */
   public String toString ()
   {
     return "ObjectStreamField< " + type + " " + name + " >";
diff --git a/java/io/PushbackReader.java b/java/io/PushbackReader.java
index 4b442e52c..cc2473a6c 100644
--- a/java/io/PushbackReader.java
+++ b/java/io/PushbackReader.java
@@ -266,33 +266,34 @@ public class PushbackReader extends FilterReader
    * of the chars requested, the remaining chars are read from the 
    * underlying stream.
    *
-   * @param buf The array into which the chars read should be stored
+   * @param buffer The array into which the chars read should be stored
    * @param offset The offset into the array to start storing chars
-   * @param len The requested number of chars to read
+   * @param length The requested number of chars to read
    *
    * @return The actual number of chars read, or -1 if end of stream.
    *
    * @exception IOException If an error occurs.
    */
-  public synchronized int read(char[] b, int offset, int len) throws IOException
+  public synchronized int read(char[] buffer, int offset, int length)
+    throws IOException
   {
     synchronized (lock)
       {
 	if (buf == null)
           throw new IOException("stream closed");
 
-	if (offset < 0 || len < 0 || offset + len > b.length)
+	if (offset < 0 || length < 0 || offset + length > buffer.length)
           throw new ArrayIndexOutOfBoundsException();
 
-	int numBytes = Math.min(buf.length - pos, len);
+	int numBytes = Math.min(buf.length - pos, length);
 	if (numBytes > 0)
 	  {
-	    System.arraycopy (buf, pos, b, offset, numBytes);
+	    System.arraycopy (buf, pos, buffer, offset, numBytes);
 	    pos += numBytes;
 	    return numBytes;
 	  }
 
-	return super.read(b, offset, len);
+	return super.read(buffer, offset, length);
       }
   }
 
@@ -353,30 +354,30 @@ public class PushbackReader extends FilterReader
    * If the pushback buffer cannot hold all of the requested chars, an
    * exception is thrown.
    *
-   * @param buf The char array to be pushed back
+   * @param buffer The char array to be pushed back
    * @param offset The index into the array where the chars to be push start
-   * @param len The number of chars to be pushed.
+   * @param length The number of chars to be pushed.
    *
    * @exception IOException If the pushback buffer is full
    */
-  public synchronized void unread(char[] b, int offset, int len)
+  public synchronized void unread(char[] buffer, int offset, int length)
     throws IOException
   {
     synchronized (lock)
       {
 	if (buf == null)
           throw new IOException("stream closed");
-	if (pos < len)
+	if (pos < length)
 	  throw new IOException("Pushback buffer is full");
 
 	// Note the order that these chars are being added is the opposite
 	// of what would be done if they were added to the buffer one at a time.
 	// See the Java Class Libraries book p. 1397.
-	System.arraycopy(b, offset, buf, pos - len, len);
+	System.arraycopy(buffer, offset, buf, pos - length, length);
 
 	// Don't put this into the arraycopy above, an exception might be thrown
 	// and in that case we don't want to modify pos.
-	pos -= len;
+	pos -= length;
       }
   }
 }
diff --git a/java/io/StringWriter.java b/java/io/StringWriter.java
index 660ef166a..63d39fb4c 100644
--- a/java/io/StringWriter.java
+++ b/java/io/StringWriter.java
@@ -60,6 +60,8 @@ public class StringWriter extends Writer
   /**
    * This method closes the stream.  The contents of the internal buffer
    * can still be retrieved, but future writes are not guaranteed to work.
+   *
+   * @excepttion IOException If an error orrurs.
    */
   public void close () throws IOException
   {
diff --git a/java/io/Writer.java b/java/io/Writer.java
index f3d6eaa73..60939c8ce 100644
--- a/java/io/Writer.java
+++ b/java/io/Writer.java
@@ -75,8 +75,8 @@ public abstract class Writer
    * 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
+   * @param lock The <code>Object</code> to use for synchronizing critical
+   *             sections
    */
   protected Writer(Object lock)
   {
@@ -157,7 +157,7 @@ public abstract class Writer
    *
    * @param str The <code>String</code> whose chars are to be written.
    *
-   * @param IOException If an error occurs
+   * @exception IOException If an error occurs
    */
   public void write(String str) throws IOException
   {