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.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@64780 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 161 insertions, 164 deletions

diff --git a/libjava/java/io/ObjectOutputStream.java b/libjava/java/io/ObjectOutputStream.java
index a051a96f3d8..afa0acb8abf 100644
--- a/libjava/java/io/ObjectOutputStream.java
+++ b/libjava/java/io/ObjectOutputStream.java
@@ -49,86 +49,85 @@ import gnu.java.lang.reflect.TypeSignature;
 import gnu.classpath.Configuration;
 
 /**
-   An <code>ObjectOutputStream</code> can be used to write objects
-   as well as primitive data in a platform-independent manner to an
-   <code>OutputStream</code>.
-
-   The data produced by an <code>ObjectOutputStream</code> can be read
-   and reconstituted by an <code>ObjectInputStream</code>.
-
-   <code>writeObject (Object)</code> is used to write Objects, the
-   <code>write&lt;type&gt;</code> methods are used to write primitive
-   data (as in <code>DataOutputStream</code>). Strings can be written
-   as objects or as primitive data.
-
-   Not all objects can be written out using an
-   <code>ObjectOutputStream</code>.  Only those objects that are an
-   instance of <code>java.io.Serializable</code> can be written.
-
-   Using default serialization, information about the class of an
-   object is written, all of the non-transient, non-static fields of
-   the object are written, if any of these fields are objects, they are
-   written out in the same manner.
-
-   An object is only written out the first time it is encountered.  If
-   the object is encountered later, a reference to it is written to
-   the underlying stream.  Thus writing circular object graphs
-   does not present a problem, nor are relationships between objects
-   in a graph lost.
-
-   Example usage:
-   <pre>
-   Hashtable map = new Hashtable ();
-   map.put ("one", new Integer (1));
-   map.put ("two", new Integer (2));
-
-   ObjectOutputStream oos =
-   new ObjectOutputStream (new FileOutputStream ("numbers"));
-   oos.writeObject (map);
-   oos.close ();
-
-   ObjectInputStream ois =
-   new ObjectInputStream (new FileInputStream ("numbers"));
-   Hashtable newmap = (Hashtable)ois.readObject ();
-
-   System.out.println (newmap);
-   </pre>
-
-   The default serialization can be overriden in two ways.
-
-   By defining a method <code>private void
-   writeObject (ObjectOutputStream)</code>, a class can dictate exactly
-   how information about itself is written.
-   <code>defaultWriteObject ()</code> may be called from this method to
-   carry out default serialization.  This method is not
-   responsible for dealing with fields of super-classes or subclasses.
-
-   By implementing <code>java.io.Externalizable</code>.  This gives
-   the class complete control over the way it is written to the
-   stream.  If this approach is used the burden of writing superclass
-   and subclass data is transfered to the class implementing
-   <code>java.io.Externalizable</code>.
-
-   @see java.io.DataOutputStream
-   @see java.io.Externalizable
-   @see java.io.ObjectInputStream
-   @see java.io.Serializable
-   @see XXX: java serialization spec
-*/
+ * An <code>ObjectOutputStream</code> can be used to write objects
+ * as well as primitive data in a platform-independent manner to an
+ * <code>OutputStream</code>.
+ *
+ * The data produced by an <code>ObjectOutputStream</code> can be read
+ * and reconstituted by an <code>ObjectInputStream</code>.
+ *
+ * <code>writeObject (Object)</code> is used to write Objects, the
+ * <code>write&lt;type&gt;</code> methods are used to write primitive
+ * data (as in <code>DataOutputStream</code>). Strings can be written
+ * as objects or as primitive data.
+ *
+ * Not all objects can be written out using an
+ * <code>ObjectOutputStream</code>.  Only those objects that are an
+ * instance of <code>java.io.Serializable</code> can be written.
+ *
+ * Using default serialization, information about the class of an
+ * object is written, all of the non-transient, non-static fields of
+ * the object are written, if any of these fields are objects, they are
+ * written out in the same manner.
+ *
+ * An object is only written out the first time it is encountered.  If
+ * the object is encountered later, a reference to it is written to
+ * the underlying stream.  Thus writing circular object graphs
+ * does not present a problem, nor are relationships between objects
+ * in a graph lost.
+ *
+ * Example usage:
+ * <pre>
+ * Hashtable map = new Hashtable ();
+ * map.put ("one", new Integer (1));
+ * map.put ("two", new Integer (2));
+ *
+ * ObjectOutputStream oos =
+ * new ObjectOutputStream (new FileOutputStream ("numbers"));
+ * oos.writeObject (map);
+ * oos.close ();
+ *
+ * ObjectInputStream ois =
+ * new ObjectInputStream (new FileInputStream ("numbers"));
+ * Hashtable newmap = (Hashtable)ois.readObject ();
+ *
+ * System.out.println (newmap);
+ * </pre>
+ *
+ * The default serialization can be overriden in two ways.
+ *
+ * By defining a method <code>private void
+ * writeObject (ObjectOutputStream)</code>, a class can dictate exactly
+ * how information about itself is written.
+ * <code>defaultWriteObject ()</code> may be called from this method to
+ * carry out default serialization.  This method is not
+ * responsible for dealing with fields of super-classes or subclasses.
+ *
+ * By implementing <code>java.io.Externalizable</code>.  This gives
+ * the class complete control over the way it is written to the
+ * stream.  If this approach is used the burden of writing superclass
+ * and subclass data is transfered to the class implementing
+ * <code>java.io.Externalizable</code>.
+ *
+ * @see java.io.DataOutputStream
+ * @see java.io.Externalizable
+ * @see java.io.ObjectInputStream
+ * @see java.io.Serializable
+ */
 public class ObjectOutputStream extends OutputStream
   implements ObjectOutput, ObjectStreamConstants
 {
   /**
-     Creates a new <code>ObjectOutputStream</code> that will do all of
-     its writing onto <code>out</code>.  This method also initializes
-     the stream by writing the header information (stream magic number
-     and stream version).
-
-     @exception IOException Writing stream header to underlying
-     stream cannot be completed.
-
-     @see writeStreamHeader ()
-  */
+   * Creates a new <code>ObjectOutputStream</code> that will do all of
+   * its writing onto <code>out</code>.  This method also initializes
+   * the stream by writing the header information (stream magic number
+   * and stream version).
+   *
+   * @exception IOException Writing stream header to underlying
+   * stream cannot be completed.
+   *
+   * @see #writeStreamHeader()
+   */
   public ObjectOutputStream (OutputStream out) throws IOException
   {
     realOutput = new DataOutputStream (out);
@@ -145,26 +144,25 @@ public class ObjectOutputStream extends OutputStream
     writeStreamHeader ();
   }
 
-
   /**
-     Writes a representation of <code>obj</code> to the underlying
-     output stream by writing out information about its class, then
-     writing out each of the objects non-transient, non-static
-     fields.  If any of these fields are other objects,
-     they are written out in the same manner.
-
-     This method can be overriden by a class by implementing
-     <code>private void writeObject (ObjectOutputStream)</code>.
-
-     If an exception is thrown from this method, the stream is left in
-     an undefined state.
-
-     @exception NotSerializableException An attempt was made to
-     serialize an <code>Object</code> that is not serializable.
-
-     @exception IOException Exception from underlying
-     <code>OutputStream</code>.
-  */
+   * Writes a representation of <code>obj</code> to the underlying
+   * output stream by writing out information about its class, then
+   * writing out each of the objects non-transient, non-static
+   * fields.  If any of these fields are other objects,
+   * they are written out in the same manner.
+   *
+   * This method can be overriden by a class by implementing
+   * <code>private void writeObject (ObjectOutputStream)</code>.
+   *
+   * If an exception is thrown from this method, the stream is left in
+   * an undefined state.
+   *
+   * @exception NotSerializableException An attempt was made to
+   * serialize an <code>Object</code> that is not serializable.
+   *
+   * @exception IOException Exception from underlying
+   * <code>OutputStream</code>.
+   */
   public final void writeObject (Object obj) throws IOException
   {
     if (useSubclassMethod)
@@ -494,7 +492,7 @@ public class ObjectOutputStream extends OutputStream
      @exception IOException if <code>version</code> is not a valid
      protocol
 
-     @see setDefaultProtocolVersion (int)
+     @see #setDefaultProtocolVersion(int)
   */
   public void useProtocolVersion (int version) throws IOException
   {
@@ -517,7 +515,7 @@ public class ObjectOutputStream extends OutputStream
      @exception IOException if <code>version</code> is not a valid
      protocol
 
-     @see useProtocolVersion (int)
+     @see #useProtocolVersion(int)
   */
   public static void setDefaultProtocolVersion (int version)
     throws IOException
@@ -538,7 +536,7 @@ public class ObjectOutputStream extends OutputStream
      @exception IOException Exception from underlying
      <code>OutputStream</code>.
 
-     @see java.io.ObjectInputStream#resolveClass (java.io.ObjectStreamClass)
+     @see ObjectInputStream#resolveClass(java.io.ObjectStreamClass)
   */
   protected void annotateClass (Class cl) throws IOException
   {}
@@ -558,7 +556,7 @@ public class ObjectOutputStream extends OutputStream
      @exception IOException Exception from underlying
      <code>OutputStream</code>.
 
-     @see enableReplaceObject (boolean)
+     @see #enableReplaceObject(boolean)
   */
   protected Object replaceObject (Object obj) throws IOException
   {
@@ -606,16 +604,16 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     Protected constructor that allows subclasses to override
-     serialization.  This constructor should be called by subclasses
-     that wish to override <code>writeObject (Object)</code>.  This
-     method does a security check <i>NOTE: currently not
-     implemented</i>, then sets a flag that informs
-     <code>writeObject (Object)</code> to call the subclasses
-     <code>writeObjectOverride (Object)</code> method.
-
-     @see writeObjectOverride (Object)
-  */
+   * Protected constructor that allows subclasses to override
+   * serialization.  This constructor should be called by subclasses
+   * that wish to override <code>writeObject (Object)</code>.  This
+   * method does a security check <i>NOTE: currently not
+   * implemented</i>, then sets a flag that informs
+   * <code>writeObject (Object)</code> to call the subclasses
+   * <code>writeObjectOverride (Object)</code> method.
+   *
+   * @see #writeObjectOverride(Object)
+   */
   protected ObjectOutputStream () throws IOException, SecurityException
   {
     SecurityManager sec_man = System.getSecurityManager ();
@@ -626,17 +624,17 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     This method allows subclasses to override the default
-     serialization mechanism provided by
-     <code>ObjectOutputStream</code>.  To make this method be used for
-     writing objects, subclasses must invoke the 0-argument
-     constructor on this class from there constructor.
-
-     @see ObjectOutputStream ()
-
-     @exception NotActiveException Subclass has arranged for this
-     method to be called, but did not implement this method.
-  */
+   * This method allows subclasses to override the default
+   * serialization mechanism provided by
+   * <code>ObjectOutputStream</code>.  To make this method be used for
+   * writing objects, subclasses must invoke the 0-argument
+   * constructor on this class from there constructor.
+   *
+   * @see #ObjectOutputStream()
+   *
+   * @exception NotActiveException Subclass has arranged for this
+   * method to be called, but did not implement this method.
+   */
   protected void writeObjectOverride (Object obj) throws NotActiveException,
     IOException
   {
@@ -645,8 +643,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#write (int)
-  */
+   * @see DataOutputStream#write(int)
+   */
   public void write (int data) throws IOException
   {
     if (writeDataAsBlocks)
@@ -662,8 +660,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#write (byte[])
-  */
+   * @see DataOutputStream#write(byte[])
+   */
   public void write (byte[] b) throws IOException
   {
     write (b, 0, b.length);
@@ -671,8 +669,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#write (byte[],int,int)
-  */
+   * @see DataOutputStream#write(byte[],int,int)
+   */
   public void write (byte[] b, int off, int len) throws IOException
   {
     if (writeDataAsBlocks)
@@ -698,8 +696,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#flush ()
-  */
+   * @see DataOutputStream#flush()
+   */
   public void flush () throws IOException
   {
     drain ();
@@ -708,12 +706,12 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     Causes the block-data buffer to be written to the underlying
-     stream, but does not flush underlying stream.
-
-     @exception IOException Exception from underlying
-     <code>OutputStream</code>.
-  */
+   * Causes the block-data buffer to be written to the underlying
+   * stream, but does not flush underlying stream.
+   *
+   * @exception IOException Exception from underlying
+   * <code>OutputStream</code>.
+   */
   protected void drain () throws IOException
   {
     if (blockDataCount == 0)
@@ -727,8 +725,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#close ()
-  */
+   * @see java.io.DataOutputStream#close ()
+   */
   public void close () throws IOException
   {
     flush ();
@@ -737,8 +735,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeBoolean (boolean)
-  */
+   * @see java.io.DataOutputStream#writeBoolean (boolean)
+   */
   public void writeBoolean (boolean data) throws IOException
   {
     blockDataOutput.writeBoolean (data);
@@ -746,8 +744,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeByte (int)
-  */
+   * @see java.io.DataOutputStream#writeByte (int)
+   */
   public void writeByte (int data) throws IOException
   {
     blockDataOutput.writeByte (data);
@@ -755,8 +753,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeShort (int)
-  */
+   * @see java.io.DataOutputStream#writeShort (int)
+   */
   public void writeShort (int data) throws IOException
   {
     blockDataOutput.writeShort (data);
@@ -764,8 +762,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeChar (int)
-  */
+   * @see java.io.DataOutputStream#writeChar (int)
+   */
   public void writeChar (int data) throws IOException
   {
     blockDataOutput.writeChar (data);
@@ -773,8 +771,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeInt (int)
-  */
+   * @see java.io.DataOutputStream#writeInt (int)
+   */
   public void writeInt (int data) throws IOException
   {
     blockDataOutput.writeInt (data);
@@ -782,8 +780,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeLong (long)
-  */
+   * @see java.io.DataOutputStream#writeLong (long)
+   */
   public void writeLong (long data) throws IOException
   {
     blockDataOutput.writeLong (data);
@@ -791,8 +789,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeFloat (float)
-  */
+   * @see java.io.DataOutputStream#writeFloat (float)
+   */
   public void writeFloat (float data) throws IOException
   {
     blockDataOutput.writeFloat (data);
@@ -800,8 +798,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeDouble (double)
-  */
+   * @see java.io.DataOutputStream#writeDouble (double)
+   */
   public void writeDouble (double data) throws IOException
   {
     blockDataOutput.writeDouble (data);
@@ -809,8 +807,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeBytes (java.lang.String)
-  */
+   * @see java.io.DataOutputStream#writeBytes (java.lang.String)
+   */
   public void writeBytes (String data) throws IOException
   {
     blockDataOutput.writeBytes (data);
@@ -818,8 +816,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeChars (java.lang.String)
-  */
+   * @see java.io.DataOutputStream#writeChars (java.lang.String)
+   */
   public void writeChars (String data) throws IOException
   {
     dataOutput.writeChars (data);
@@ -827,8 +825,8 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     @see java.io.DataOutputStream#writeUTF (java.lang.String)
-  */
+   * @see java.io.DataOutputStream#writeUTF (java.lang.String)
+   */
   public void writeUTF (String data) throws IOException
   {
     dataOutput.writeUTF (data);
@@ -836,11 +834,11 @@ public class ObjectOutputStream extends OutputStream
 
 
   /**
-     This class allows a class to specify exactly which fields should
-     be written, and what values should be written for these fields.
-
-     XXX: finish up comments
-  */
+   * This class allows a class to specify exactly which fields should
+   * be written, and what values should be written for these fields.
+   *
+   * XXX: finish up comments
+   */
   public static abstract class PutField
   {
     public abstract void put (String name, boolean value)
@@ -864,7 +862,6 @@ public class ObjectOutputStream extends OutputStream
     public abstract void write (ObjectOutput out) throws IOException;
   }
 
-
   public PutField putFields () throws IOException
   {
     markFieldsWritten ();