AbstractMethodError.java: Re-merged with Classpath.

	* java/lang/AbstractMethodError.java: Re-merged with Classpath.
	* java/lang/ArithmeticException.java: Likewise.
	* java/lang/ArrayIndexOutOfBoundsException.java: Likewise.
	* java/lang/ArrayStoreException.java: Likewise.
	* java/lang/Byte.java: Likewise.
	* java/lang/CharSequence.java: Likewise.
	* java/lang/ClassCastException.java: Likewise.
	* java/lang/ClassCircularityError.java: Likewise.
	* java/lang/ClassFormatError.java: Likewise.
	* java/lang/CloneNotSupportedException.java: Likewise.
	* java/lang/Cloneable.java: Likewise.
	* java/lang/Comparable.java: Likewise.
	* java/lang/Compiler.java: Likewise.
	* java/lang/Error.java: Likewise.
	* java/lang/ExceptionInInitializerError.java: Likewise.
	* java/lang/IllegalAccessError.java: Likewise.
	* java/lang/IllegalAccessException.java: Likewise.
	* java/lang/IllegalArgumentException.java: Likewise.
	* java/lang/IllegalMonitorStateException.java: Likewise.
	* java/lang/IllegalStateException.java: Likewise.
	* java/lang/IllegalThreadStateException.java: Likewise.
	* java/lang/IncompatibleClassChangeError.java: Likewise.
	* java/lang/IndexOutOfBoundsException.java: Likewise.
	* java/lang/InheritableThreadLocal.java: Likewise.
	* java/lang/InstantiationError.java: Likewise.
	* java/lang/InstantiationException.java: Likewise.
	* java/lang/InternalError.java: Likewise.
	* java/lang/InterruptedException.java: Likewise.
	* java/lang/LinkageError.java: Likewise.
	* java/lang/NegativeArraySizeException.java: Likewise.
	* java/lang/NoClassDefFoundError.java: Likewise.
	* java/lang/NoSuchFieldError.java: Likewise.
	* java/lang/NoSuchFieldException.java: Likewise.
	* java/lang/NoSuchMethodError.java: Likewise.
	* java/lang/NoSuchMethodException.java: Likewise.
	* java/lang/NullPointerException.java: Likewise.
	* java/lang/NumberFormatException.java: Likewise.
	* java/lang/OutOfMemoryError.java: Likewise.
	* java/lang/Process.java: Likewise.
	* java/lang/Runnable.java: Likewise.
	* java/lang/RuntimePermission.java: Likewise.
	* java/lang/SecurityException.java: Likewise.
	* java/lang/Short.java: Likewise.
	* java/lang/StackOverflowError.java: Likewise.
	* java/lang/StringIndexOutOfBoundsException.java: Likewise.
	* java/lang/ThreadDeath.java: Likewise.
	* java/lang/ThreadLocal.java: Likewise.
	* java/lang/UnknownError.java: Likewise.
	* java/lang/UnsatisfiedLinkError.java: Likewise.
	* java/lang/UnsupportedClassVersionError.java: Likewise.
	* java/lang/UnsupportedOperationException.java: Likewise.
	* java/lang/VerifyError.java: Likewise.
	* java/lang/VirtualMachineError.java: Likewise.
	* java/lang/reflect/InvocationTargetException.java: Likewise.
	* java/net/BindException.java: Likewise.
	* java/net/ConnectException.java: Likewise.
	* java/net/MalformedURLException.java: Likewise.
	* java/net/NoRouteToHostException.java: Likewise.
	* java/net/ProtocolException.java: Likewise.
	* java/net/SocketException.java: Likewise.
	* java/net/UnknownHostException.java: Likewise.
	* java/net/UnknownServiceException.java: Likewise.

From-SVN: r54656

63 files changed, 2151 insertions, 2199 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index a6b89c1..3878c34 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,5 +1,68 @@
 2002-06-15  Tom Tromey  <tromey@redhat.com>
 
+	* java/lang/AbstractMethodError.java: Re-merged with Classpath.
+	* java/lang/ArithmeticException.java: Likewise.
+	* java/lang/ArrayIndexOutOfBoundsException.java: Likewise.
+	* java/lang/ArrayStoreException.java: Likewise.
+	* java/lang/Byte.java: Likewise.
+	* java/lang/CharSequence.java: Likewise.
+	* java/lang/ClassCastException.java: Likewise.
+	* java/lang/ClassCircularityError.java: Likewise.
+	* java/lang/ClassFormatError.java: Likewise.
+	* java/lang/CloneNotSupportedException.java: Likewise.
+	* java/lang/Cloneable.java: Likewise.
+	* java/lang/Comparable.java: Likewise.
+	* java/lang/Compiler.java: Likewise.
+	* java/lang/Error.java: Likewise.
+	* java/lang/ExceptionInInitializerError.java: Likewise.
+	* java/lang/IllegalAccessError.java: Likewise.
+	* java/lang/IllegalAccessException.java: Likewise.
+	* java/lang/IllegalArgumentException.java: Likewise.
+	* java/lang/IllegalMonitorStateException.java: Likewise.
+	* java/lang/IllegalStateException.java: Likewise.
+	* java/lang/IllegalThreadStateException.java: Likewise.
+	* java/lang/IncompatibleClassChangeError.java: Likewise.
+	* java/lang/IndexOutOfBoundsException.java: Likewise.
+	* java/lang/InheritableThreadLocal.java: Likewise.
+	* java/lang/InstantiationError.java: Likewise.
+	* java/lang/InstantiationException.java: Likewise.
+	* java/lang/InternalError.java: Likewise.
+	* java/lang/InterruptedException.java: Likewise.
+	* java/lang/LinkageError.java: Likewise.
+	* java/lang/NegativeArraySizeException.java: Likewise.
+	* java/lang/NoClassDefFoundError.java: Likewise.
+	* java/lang/NoSuchFieldError.java: Likewise.
+	* java/lang/NoSuchFieldException.java: Likewise.
+	* java/lang/NoSuchMethodError.java: Likewise.
+	* java/lang/NoSuchMethodException.java: Likewise.
+	* java/lang/NullPointerException.java: Likewise.
+	* java/lang/NumberFormatException.java: Likewise.
+	* java/lang/OutOfMemoryError.java: Likewise.
+	* java/lang/Process.java: Likewise.
+	* java/lang/Runnable.java: Likewise.
+	* java/lang/RuntimePermission.java: Likewise.
+	* java/lang/SecurityException.java: Likewise.
+	* java/lang/Short.java: Likewise.
+	* java/lang/StackOverflowError.java: Likewise.
+	* java/lang/StringIndexOutOfBoundsException.java: Likewise.
+	* java/lang/ThreadDeath.java: Likewise.
+	* java/lang/ThreadLocal.java: Likewise.
+	* java/lang/UnknownError.java: Likewise.
+	* java/lang/UnsatisfiedLinkError.java: Likewise.
+	* java/lang/UnsupportedClassVersionError.java: Likewise.
+	* java/lang/UnsupportedOperationException.java: Likewise.
+	* java/lang/VerifyError.java: Likewise.
+	* java/lang/VirtualMachineError.java: Likewise.
+	* java/lang/reflect/InvocationTargetException.java: Likewise.
+	* java/net/BindException.java: Likewise.
+	* java/net/ConnectException.java: Likewise.
+	* java/net/MalformedURLException.java: Likewise.
+	* java/net/NoRouteToHostException.java: Likewise.
+	* java/net/ProtocolException.java: Likewise.
+	* java/net/SocketException.java: Likewise.
+	* java/net/UnknownHostException.java: Likewise.
+	* java/net/UnknownServiceException.java: Likewise.
+
 	* java/io/BufferedOutputStream.java: Re-merged with Classpath.
 	* java/io/CharConversionException.java: Likewise.
 	* java/io/EOFException.java: Likewise.
diff --git a/libjava/java/lang/AbstractMethodError.java b/libjava/java/lang/AbstractMethodError.java
index eb96b23..df96186 100644
--- a/libjava/java/lang/AbstractMethodError.java
+++ b/libjava/java/lang/AbstractMethodError.java
@@ -1,5 +1,5 @@
-/* AbstractMethodError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* AbstractMethodError.java -- thrown if an abstract method is invoked
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,41 +38,38 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * An <code>AbstractMethodError</code> is thrown when an application
- * attempts to access an abstract method.  Compilers typically detect
- * this error, but it can be thrown at run time if the definition of a 
- * class has changed since the application was last compiled.
+ * An <code>AbstractMethodError</code> is thrown when an application attempts
+ * to access an abstract method.  Compilers typically detect this error, but
+ * it can be thrown at run time if the definition of a class has changed
+ * since the application was last compiled. This can also occur when
+ * reflecting on methods.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class AbstractMethodError extends IncompatibleClassChangeError
 {
-  static final long serialVersionUID = -1654391082989018462L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -1654391082989018462L;
 
   /**
    * Create an error without a message.
    */
   public AbstractMethodError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public AbstractMethodError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/ArithmeticException.java b/libjava/java/lang/ArithmeticException.java
index 43f019c..de79b09 100644
--- a/libjava/java/lang/ArithmeticException.java
+++ b/libjava/java/lang/ArithmeticException.java
@@ -1,6 +1,6 @@
 /* ArithmeticException.java -- exception thrown to indicate conditions
    like divide by zero.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,41 +39,39 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional circumstances.
- * In this case an ArithmeticException is thrown when things like trying
- * to divide a number by zero.
- *
- * @since JDK 1.0
+ * Thrown when a math error has occured, such as trying to divide an
+ * integer by zero. For example:<br>
+ * <pre>
+ * int i = 0;
+ * int j = 2 / i;
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class ArithmeticException extends RuntimeException
 {
-  static final long serialVersionUID = 2256477558314496007L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 2256477558314496007L;
 
   /**
    * Create an exception without a message.
    */
   public ArithmeticException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public ArithmeticException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/ArrayIndexOutOfBoundsException.java b/libjava/java/lang/ArrayIndexOutOfBoundsException.java
index bdb3628..1a6db8d 100644
--- a/libjava/java/lang/ArrayIndexOutOfBoundsException.java
+++ b/libjava/java/lang/ArrayIndexOutOfBoundsException.java
@@ -1,6 +1,6 @@
 /* ArrayIndexOutOfBoundsException.java -- exception thrown when accessing
    an illegal index.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,49 +39,49 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions, in this case
- * when trying to access an illegal index.  This exception is thrown when
- * accessing an index which is either negative or greater than the size of
- * the array minus one.
- *
- * @since JDK 1.0
+ * Thrown when attempting to access a position outside the valid range of
+ * an array. For example:<br>
+ * <pre>
+ * int[] i = { 1 };
+ * i[1] = 2;
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class ArrayIndexOutOfBoundsException extends IndexOutOfBoundsException
 {
-  static final long serialVersionUID = -5116101128118950844L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -5116101128118950844L;
 
   /**
    * Create an exception without a message.
    */
-  public ArrayIndexOutOfBoundsException() {
-    super();
+  public ArrayIndexOutOfBoundsException()
+  {
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
-  public ArrayIndexOutOfBoundsException(String s) {
+  public ArrayIndexOutOfBoundsException(String s)
+  {
     super(s);
   }
 
   /**
    * Create an exception indicating the illegal index.
+   *
+   * @param index the invalid index
    */
-  public ArrayIndexOutOfBoundsException(int index) {
+  public ArrayIndexOutOfBoundsException(int index)
+  {
     super("Array index out of range: " + index);
   }
-
 }
diff --git a/libjava/java/lang/ArrayStoreException.java b/libjava/java/lang/ArrayStoreException.java
index b3e12fd..3fa714d 100644
--- a/libjava/java/lang/ArrayStoreException.java
+++ b/libjava/java/lang/ArrayStoreException.java
@@ -1,6 +1,6 @@
 /* ArrayStoreException.java -- exception thrown to when trying to store an
    object into an array of a different type.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,40 +39,39 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions, in this case
- * when trying to store an object into an array of a different type.
- *
- * @since JDK 1.0
+ * Thrown when trying to store an object of the wrong runtime type in an
+ * array. For example:<br>
+ * <pre>
+ * Object[] o = new Integer[1];
+ * o[0] = "oops";
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class ArrayStoreException extends RuntimeException
 {
-  static final long serialVersionUID = -4522193890499838241L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4522193890499838241L;
 
   /**
    * Create an exception without a message.
    */
   public ArrayStoreException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public ArrayStoreException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/Byte.java b/libjava/java/lang/Byte.java
index eab2d53..7605ad7 100644
--- a/libjava/java/lang/Byte.java
+++ b/libjava/java/lang/Byte.java
@@ -1,5 +1,5 @@
 /* Byte.java -- object wrapper for byte
-   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -48,267 +48,310 @@ package java.lang;
  * @author Paul Fisher
  * @author John Keiser
  * @author Per Bothner
- * @since JDK 1.0
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.1
+ * @status updated to 1.4
  */
-public final class Byte extends Number implements Comparable 
+public final class Byte extends Number implements Comparable
 {
-  static final long serialVersionUID = -7183698231559129828L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = -7183698231559129828L;
 
   /**
-   * The minimum value a <code>byte</code> can represent is -128.
+   * The minimum value a <code>byte</code> can represent is -128 (or
+   * -2<sup>7</sup>).
    */
   public static final byte MIN_VALUE = -128;
 
   /**
-   * The maximum value a <code>byte</code> can represent is 127.
+   * The maximum value a <code>byte</code> can represent is 127 (or
+   * 2<sup>7</sup> - 1).
    */
   public static final byte MAX_VALUE = 127;
 
   /**
-   * The primitive type <code>byte</code> is represented by this 
+   * The primitive type <code>byte</code> is represented by this
    * <code>Class</code> object.
    */
   public static final Class TYPE = VMClassLoader.getPrimitiveClass('B');
 
   /**
    * The immutable value of this Byte.
+   *
+   * @serial the wrapped byte
    */
   private final byte value;
 
   /**
-   * Create a <code>Byte</code> object representing the value of the 
+   * Create a <code>Byte</code> object representing the value of the
    * <code>byte</code> argument.
    *
    * @param value the value to use
-   */     
-  public Byte(byte value) 
+   */
+  public Byte(byte value)
   {
     this.value = value;
   }
 
   /**
-   * Create a <code>Byte</code> object representing the value specified 
-   * by the <code>String</code> argument.
+   * Create a <code>Byte</code> object representing the value specified
+   * by the <code>String</code> argument
    *
-   * @param s the string to convert.
+   * @param s the string to convert
+   * @throws NumberFormatException if the String does not contain a byte
+   * @see #valueOf(String)
    */
-  public Byte(String s) throws NumberFormatException 
+  public Byte(String s)
   {
     value = parseByte(s, 10);
   }
 
   /**
-   * Return a hashcode representing this Object.
-   *
-   * <code>Byte</code>'s hash code is calculated by simply returning its
-   * value.
+   * Converts the <code>byte</code> to a <code>String</code> and assumes
+   * a radix of 10.
    *
-   * @return this Object's hash code.
+   * @param b the <code>byte</code> to convert to <code>String</code>
+   * @return the <code>String</code> representation of the argument
    */
-  public int hashCode() 
+  public static String toString(byte b)
   {
-    return value;
+    return String.valueOf(b);
   }
 
   /**
-   * Returns <code>true</code> if <code>obj</code> is an instance of
-   * <code>Byte</code> and represents the same byte value.
-   * @return whether these Objects are semantically equal.
-   */    
-  public boolean equals(Object obj) 
-  {
-    return ((obj instanceof Byte) && (value == ((Byte)obj).byteValue()));
-  }
-
-  /**
-   * Converts the <code>byte</code> to a <code>String</code> and assumes
-   * a radix of 10.
-   * @param i the <code>byte</code> to convert to <code>String</code>
-   * @return the <code>String</code> representation of the argument.
-   */    
-  public static String toString(byte i) 
+   * Converts the specified <code>String</code> into a <code>byte</code>.
+   * This function assumes a radix of 10.
+   *
+   * @param s the <code>String</code> to convert
+   * @return the <code>byte</code> value of <code>s</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
+   * @see #parseByte(String)
+   */
+  public static byte parseByte(String s)
   {
-    return Integer.toString ((int) i);
+    return parseByte(s, 10);
   }
 
   /**
-   * Converts the <code>Byte</code> value to a <code>String</code> and
-   * assumes a radix of 10.
-   * @return the <code>String</code> representation of this <code>Byte</code>.
-   */    
-  public String toString() 
-  {
-    return Integer.toString ((int) value);
-  }
-    
-  /**
-   * Creates a new <code>Byte</code> object using the <code>String</code>,
-   * assuming a radix of 10.
-   * @param s the <code>String</code> to convert.
-   * @return the new <code>Byte</code>.
-   * @see #Byte(java.lang.String)
-   * @see #parseByte(java.lang.String)
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.
+   * Converts the specified <code>String</code> into an <code>int</code>
+   * using the specified radix (base). The string must not be <code>null</code>
+   * or empty. It may begin with an optional '-', which will negate the answer,
+   * provided that there are also valid digits. Each digit is parsed as if by
+   * <code>Character.digit(d, radix)</code>, and must be in the range
+   * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
+   * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
+   * Unlike Double.parseDouble, you may not have a leading '+'.
+   *
+   * @param s the <code>String</code> to convert
+   * @param radix the radix (base) to use in the conversion
+   * @return the <code>String</code> argument converted to </code>byte</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
    */
-  public static Byte valueOf(String s) throws NumberFormatException 
+  public static byte parseByte(String s, int radix)
   {
-    return new Byte(parseByte(s));
+    int i = Integer.parseInt(s, radix, false);
+    if ((byte) i != i)
+      throw new NumberFormatException();
+    return (byte) i;
   }
 
   /**
    * Creates a new <code>Byte</code> object using the <code>String</code>
    * and specified radix (base).
-   * @param s the <code>String</code> to convert.
-   * @param radix the radix (base) to convert with.
-   * @return the new <code>Byte</code>.
-   * @see #parseByte(java.lang.String,int)
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.
-   */
-  public static Byte valueOf(String s, int radix) 
-    throws NumberFormatException 
-  {
-    return new Byte(parseByte(s, radix));
-  }
-
-  /**
-   * Converts the specified <code>String</code> into a <code>byte</code>.
-   * This function assumes a radix of 10.
    *
    * @param s the <code>String</code> to convert
-   * @return the <code>byte</code> value of the <code>String</code>
-   *         argument.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.
+   * @param radix the radix (base) to convert with
+   * @return the new <code>Byte</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
+   * @see #parseByte(String, int)
    */
-  public static byte parseByte(String s) throws NumberFormatException 
+  public static Byte valueOf(String s, int radix)
   {
-    return parseByte(s, 10);
+    return new Byte(parseByte(s, radix));
   }
 
   /**
-   * Converts the specified <code>String</code> into a <code>byte</code>
-   * using the specified radix (base).
+   * Creates a new <code>Byte</code> object using the <code>String</code>,
+   * assuming a radix of 10.
    *
-   * @param str the <code>String</code> to convert
-   * @param radix the radix (base) to use in the conversion
-   * @return the <code>String</code> argument converted to </code>byte</code>.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.    
+   * @param s the <code>String</code> to convert
+   * @return the new <code>Byte</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
+   * @see #Byte(String)
+   * @see #parseByte(String)
    */
-  public static byte parseByte(String str, int radix) 
-    throws NumberFormatException 
+  public static Byte valueOf(String s)
   {
-    int i = Integer.parseInt(str, radix);
-    if (i < MIN_VALUE || i > MAX_VALUE)
-      throw new NumberFormatException();
-    return (byte) i;
+    return new Byte(parseByte(s, 10));
   }
 
   /**
    * Convert the specified <code>String</code> into a <code>Byte</code>.
-   * The <code>String</code> may represent decimal, hexadecimal, or 
+   * The <code>String</code> may represent decimal, hexadecimal, or
    * octal numbers.
    *
-   * The <code>String</code> argument is interpreted based on the leading
-   * characters.  Depending on what the String begins with, the base will be
-   * interpreted differently:
+   * <p>The extended BNF grammar is as follows:<br>
+   * <pre>
+   * <em>DecodableString</em>:
+   *      ( [ <code>-</code> ] <em>DecimalNumber</em> )
+   *    | ( [ <code>-</code> ] ( <code>0x</code> | <code>0X</code>
+   *              | <code>#</code> ) { <em>HexDigit</em> }+ )
+   *    | ( [ <code>-</code> ] <code>0</code> { <em>OctalDigit</em> } )
+   * <em>DecimalNumber</em>:
+   *        <em>DecimalDigit except '0'</em> { <em>DecimalDigit</em> }
+   * <em>DecimalDigit</em>:
+   *        <em>Character.digit(d, 10) has value 0 to 9</em>
+   * <em>OctalDigit</em>:
+   *        <em>Character.digit(d, 8) has value 0 to 7</em>
+   * <em>DecimalDigit</em>:
+   *        <em>Character.digit(d, 16) has value 0 to 15</em>
+   * </pre>
+   * Finally, the value must be in the range <code>MIN_VALUE</code> to
+   * <code>MAX_VALUE</code>, or an exception is thrown.
    *
-   * <table>
-   * <tr><th>Leading<br>Characters</th><th>Base</th></tr>
-   * <tr><td>#</td><td>16</td></tr>
-   * <tr><td>0x</td><td>16</td></tr>
-   * <tr><td>0X</td><td>16</td></tr>
-   * <tr><td>0</td><td>8</td></tr>
-   * <tr><td>Anything<br>Else</td><td>10</td></tr>
-   * </table>
-   *
-   * @param str the <code>String</code> to interpret.
-   * @return the value of the String as a <code>Byte</code>.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.    
+   * @param s the <code>String</code> to interpret
+   * @return the value of the String as a <code>Byte</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
+   * @throws NullPointerException if <code>s</code> is null
+   * @see Integer#decode(String)
    */
-  public static Byte decode(String str) throws NumberFormatException 
+  public static Byte decode(String s)
   {
-    int i = (Integer.decode(str)).intValue();
-    if (i < MIN_VALUE || i > MAX_VALUE)
+    int i = Integer.parseInt(s, 10, true);
+    if ((byte) i != i)
       throw new NumberFormatException();
     return new Byte((byte) i);
   }
-    
-  /** Return the value of this <code>Byte</code> as an <code>short</code>.
-   ** @return the value of this <code>Byte</code> as an <code>short</code>.
-   **/
+
+  /**
+   * Return the value of this <code>Byte</code>.
+   *
+   * @return the byte value
+   */
   public byte byteValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as an <code>short</code>.
-   ** @return the value of this <code>Byte</code> as an <code>short</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as a <code>short</code>.
+   *
+   * @return the short value
+   */
   public short shortValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as an <code>int</code>.
-   ** @return the value of this <code>Byte</code> as an <code>int</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as an <code>int</code>.
+   *
+   * @return the int value
+   */
   public int intValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as a <code>long</code>.
-   ** @return the value of this <code>Byte</code> as a <code>long</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as a <code>long</code>.
+   *
+   * @return the long value
+   */
   public long longValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as a <code>float</code>.
-   ** @return the value of this <code>Byte</code> as a <code>float</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as a <code>float</code>.
+   *
+   * @return the float value
+   */
   public float floatValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as a <code>double</code>.
-   ** @return the value of this <code>Byte</code> as a <code>double</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as a <code>double</code>.
+   *
+   * @return the double value
+   */
   public double doubleValue()
   {
     return value;
   }
-    
+
   /**
-   * Compare two Bytes numerically by comparing their
-   * <code>byte</code> values.
-   * @return a positive value if this <code>Byte</code> is greater
-   * in value than the argument <code>Byte</code>; a negative value
-   * if this <code>Byte</code> is smaller in value than the argument
-   * <code>Byte</code>; and <code>0</code>, zero, if this
-   * <code>Byte</code> is equal in value to the argument
-   * <code>Byte</code>.  
+   * Converts the <code>Byte</code> value to a <code>String</code> and
+   * assumes a radix of 10.
+   *
+   * @return the <code>String</code> representation of this <code>Byte</code>
+   * @see Integer#toString()
+   */
+  public String toString()
+  {
+    return String.valueOf(value);
+  }
+
+  /**
+   * Return a hashcode representing this Object. <code>Byte</code>'s hash
+   * code is simply its value.
+   *
+   * @return this Object's hash code
+   */
+  public int hashCode()
+  {
+    return value;
+  }
+
+  /**
+   * Returns <code>true</code> if <code>obj</code> is an instance of
+   * <code>Byte</code> and represents the same byte value.
+   *
+   * @param obj the object to compare
+   * @return whether these Objects are semantically equal
+   */
+  public boolean equals(Object obj)
+  {
+    return obj instanceof Byte && value == ((Byte) obj).value;
+  }
+
+  /**
+   * Compare two Bytes numerically by comparing their <code>byte</code> values.
+   * The result is positive if the first is greater, negative if the second
+   * is greater, and 0 if the two are equal.
+   *
+   * @param b the Byte to compare
+   * @return the comparison
+   * @since 1.2
    */
   public int compareTo(Byte b)
   {
-    return (int)(value - b.byteValue());
+    return value - b.value;
   }
-    
+
   /**
-   * Behaves like <code>compareTo(java.lang.Byte)</code> unless the Object
-   * is not a <code>Byte</code>.  Then it throws a 
-   * <code>ClassCastException</code>.
-   * @exception ClassCastException if the argument is not a
-   * <code>Byte</code>.  
+   * Behaves like <code>compareTo(Byte)</code> unless the Object
+   * is not a <code>Byte</code>.
+   *
+   * @param o the object to compare
+   * @return the comparison
+   * @throws ClassCastException if the argument is not a <code>Byte</code>
+   * @see #compareTo(Byte)
+   * @see Comparable
+   * @since 1.2
    */
   public int compareTo(Object o)
   {
-    return compareTo((Byte)o);
+    return compareTo((Byte) o);
   }
 }
diff --git a/libjava/java/lang/CharSequence.java b/libjava/java/lang/CharSequence.java
index 880d725..d46bd9d 100644
--- a/libjava/java/lang/CharSequence.java
+++ b/libjava/java/lang/CharSequence.java
@@ -1,5 +1,5 @@
-/* java.lang.CharSequence -- Anything that has an indexed sequence of chars
-   Copyright (C) 2001 Free Software Foundation, Inc.
+/* CharSequence.java -- Anything that has an indexed sequence of chars
+   Copyright (C) 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -44,8 +44,8 @@ package java.lang;
  * <code>CharBuffer</code> to give a uniform way to get chars at a certain
  * index, the number of characters in the sequence and a subrange of the
  * chars. Indexes start at 0 and the last index is <code>length()-1</code>.
- * <p>
- * Even when classes implement this interface they are not always
+ *
+ * <p>Even when classes implement this interface they are not always
  * exchangeble because they might implement their compare, equals or hash
  * function differently. This means that in general one should not use a
  * <code>CharSequence</code> as keys in collections since two sequences
@@ -54,38 +54,46 @@ package java.lang;
  * represented by different classes.
  *
  * @author Mark Wielaard (mark@klomp.org)
- *
  * @since 1.4
+ * @status updated to 1.4
  */
+public interface CharSequence
+{
+  /**
+   * Returns the character at the given index.
+   *
+   * @param i the index to retrieve from
+   * @return the character at that location
+   * @throws IndexOutOfBoundsException if i &lt; 0 || i &gt;= length() - 1
+   */
+  char charAt(int i);
 
-public interface CharSequence {
-
-    /**
-     * Returns the character at the given index.
-     *
-     * @exception IndexOutOfBoundsException when <code>i &lt; 0</code> or
-     * <code>i &gt; length()-1</code>.
-     */
-    char charAt(int i);
-
-    /**
-     * Returns the length of the sequence.
-     */
-    int length();
+  /**
+   * Returns the length of the sequence. This is the number of 16-bit
+   * characters in the sequence, which may differ from the length of the
+   * underlying encoding.
+   *
+   * @return the sequence length
+   */
+  int length();
 
-    /**
-     * Returns a new <code>CharSequence</char> of the indicated range.
-     *
-     * @exception IndexOutOfBoundsException when <code>begin &lt; 0</code>,
-     *         <code>end &lt; 0</code>, <code>end &gt; length()</code> or
-     *         <code>begin &gt; end</code>
-     */
-    CharSequence subSequence(int begin, int end);
+  /**
+   * Returns a new <code>CharSequence</char> of the indicated range.
+   *
+   * @param begin the start index (inclusive)
+   * @param end the end index (exclusive)
+   * @return a subsequence of this
+   * @throws IndexOutOfBoundsException if begin &gt; end || begin &lt; 0 ||
+   *         end &gt; length()
+   */
+  CharSequence subSequence(int begin, int end);
 
-    /**
-     * Returns the complete <code>CharSequence</code> as a <code>String</code>.
-     * Classes that implement this interface should return a <code>String</code>
-     * which contains only the characters in the sequence in the correct order.
-     */
-    String toString();
+  /**
+   * Returns the complete <code>CharSequence</code> as a <code>String</code>.
+   * Classes that implement this interface should return a <code>String</code>
+   * which contains only the characters in the sequence in the correct order.
+   *
+   * @return the character sequence as a String
+   */
+  String toString();
 }
diff --git a/libjava/java/lang/ClassCastException.java b/libjava/java/lang/ClassCastException.java
index b130733..b552b23 100644
--- a/libjava/java/lang/ClassCastException.java
+++ b/libjava/java/lang/ClassCastException.java
@@ -1,6 +1,5 @@
-/* ClassCastException.java -- exception thrown when incorrectly trying to 
-   cast an object to a subclass it does not belong to.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* ClassCastException.java -- exception thrown on bad cast
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +7,7 @@ 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
@@ -39,45 +38,39 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  In this case
- * when incorrectly trying to cast an object to a subclass it does not 
- * belong to.  The following code generates a <code>ClassCastException</code>.
+ * Thrown when an attempt is made to cast an object which is not of the
+ * appropriate runtime type. For example:<br>
  * <pre>
  * Object o = new Vector();
- * String s = (String)o;
+ * String s = (String) o;
  * </pre>
  *
- * @since JDK 1.0
- *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class ClassCastException extends RuntimeException
 {
-  static final long serialVersionUID = -9223365651070458532L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -9223365651070458532L;
 
   /**
    * Create an exception without a message.
    */
   public ClassCastException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public ClassCastException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/ClassCircularityError.java b/libjava/java/lang/ClassCircularityError.java
index 95e292d..8016ead 100644
--- a/libjava/java/lang/ClassCircularityError.java
+++ b/libjava/java/lang/ClassCircularityError.java
@@ -1,5 +1,5 @@
-/* ClassCircularityError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* ClassCircularityError.java -- thrown when linking circular classes
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,39 +38,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
  * A <code>ClassCircularityError</code> is thrown when a circular dependency
- * has been detected while initializing a class.
+ * has been detected while initializing a class. This signals binary
+ * incompatible versions of class files, as the compiler normally catches this.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class ClassCircularityError extends LinkageError
 {
-  static final long serialVersionUID = 1054362542914539689L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 1054362542914539689L;
 
   /**
    * Create an error without a message.
    */
   public ClassCircularityError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public ClassCircularityError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/ClassFormatError.java b/libjava/java/lang/ClassFormatError.java
index 0621c85..d28cacd 100644
--- a/libjava/java/lang/ClassFormatError.java
+++ b/libjava/java/lang/ClassFormatError.java
@@ -1,5 +1,5 @@
-/* ClassFormatError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* ClassFormatError.java -- thrown if a class file is invalid
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,38 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * A <code>ClassFormatError</code> is thrown when a Java Virtual Machine 
+ * A <code>ClassFormatError</code> is thrown when a Java Virtual Machine
  * unable to read a class file because the file is corrupted or cannot be
  * interpreted as a class file.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
+ * @status updated to 1.4
  */
 public class ClassFormatError extends LinkageError
 {
-  static final long serialVersionUID = -8420114879011949195L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -8420114879011949195L;
 
   /**
    * Create an error without a message.
    */
   public ClassFormatError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public ClassFormatError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/CloneNotSupportedException.java b/libjava/java/lang/CloneNotSupportedException.java
index 128bd5b..e13112a 100644
--- a/libjava/java/lang/CloneNotSupportedException.java
+++ b/libjava/java/lang/CloneNotSupportedException.java
@@ -1,7 +1,5 @@
-/* CloneNotSupportedException.java -- exception thrown to indicate that 
-   the object calling the clone method of Object does not implement the 
-   Cloneable interface.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* CloneNotSupportedException.java -- thrown when an object cannot be cloned
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -9,7 +7,7 @@ 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
@@ -40,33 +38,38 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
  * Thrown to indicate an object should not or could not be cloned. This
  * includes the case when {@link Object#clone()} is called on an object
- * which does not implement the {@link Cloneable} interface.
- * <p>
+ * which does not implement the {@link Cloneable} interface. For example:<br>
+ * <pre>
+ * void m() throws CloneNotSupportedException
+ * {
+ *   clone();
+ * }
+ * </pre>
  *
- * Notice that calling <code>clone()</code> on an array will never produce
+ * <p>Notice that calling <code>clone()</code> on an array will never produce
  * this exception, as the VM will always succeed in copying the array, or
- * cause an OutOfMemoryError first.
+ * cause an OutOfMemoryError first. For example:<br>
+ * <pre>
+ * void m(int[] array)
+ * {
+ *   int[] copy = (int[]) array.clone();
+ * }
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
  * @author Eric Blake <ebb9@email.byu.edu>
- * @since 1.0
  * @see Cloneable
  * @see Object#clone()
+ * @status updated to 1.4
  */
 public class CloneNotSupportedException extends Exception
 {
   /**
-   * compatible with JDK 1.0+
+   * Compatible with JDK 1.0+.
    */
   private static final long serialVersionUID = 5195511250079656443L;
 
@@ -79,6 +82,7 @@ public class CloneNotSupportedException extends Exception
 
   /**
    * Create an exception with a message.
+   *
    * @param s the error message
    */
   public CloneNotSupportedException(String s)
diff --git a/libjava/java/lang/Cloneable.java b/libjava/java/lang/Cloneable.java
index 442c79c..64c7faf 100644
--- a/libjava/java/lang/Cloneable.java
+++ b/libjava/java/lang/Cloneable.java
@@ -1,5 +1,5 @@
 /* Cloneable.java -- Interface for marking objects cloneable by Object.clone()
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,12 +38,6 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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 interface should be implemented by classes wishing to
  * support of override <code>Object.clone()</code>.  The default
@@ -53,33 +47,30 @@ package java.lang;
  * If <code>clone()</code> is called on an object which does not
  * implement this interface, a <code>CloneNotSupportedException</code>
  * will be thrown.
- * <p>
  *
- * This interface is simply a tagging interface; it carries no
+ * <p>This interface is simply a tagging interface; it carries no
  * requirements on methods to implement.  However, it is typical for
  * a Cloneable class to implement at least <code>equals</code>,
  * <code>hashCode</code>, and <code>clone</code>, sometimes
  * increasing the accessibility of clone to be public. The typical
  * implementation of <code>clone</code> invokes <code>super.clone()</code>
  * rather than a constructor, but this is not a requirement.
- * <p>
  *
- * If an object that implement Cloneable should not be cloned,
+ * <p>If an object that implement Cloneable should not be cloned,
  * simply override the <code>clone</code> method to throw a
  * <code>CloneNotSupportedException</code>.
- * <p>
  *
- * All array types implement Cloneable, and have a public
+ * <p>All array types implement Cloneable, and have a public
  * <code>clone</code> method that will never fail with a
  * <code>CloneNotSupportedException</code>.
  *
- * @since 1.0
  * @author Paul Fisher
  * @author Eric Blake <ebb9@email.byu.edu>
  * @author Warren Levy <warrenl@cygnus.com>
- *
  * @see Object#clone()
  * @see CloneNotSupportedException
+ * @since 1.0
+ * @status updated to 1.4
  */
 public interface Cloneable
 {
diff --git a/libjava/java/lang/Comparable.java b/libjava/java/lang/Comparable.java
index e1e5b1b..96d4d6a 100644
--- a/libjava/java/lang/Comparable.java
+++ b/libjava/java/lang/Comparable.java
@@ -1,5 +1,5 @@
 /* Comparable.java -- Interface for comparaing objects to obtain an ordering
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,32 +38,60 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
-/** 
- * Interface for objects that can be ordering among other
- * objects. The ordering can be <EM>total</EM>, such that two objects
- * only compare equal if they are equal by the equals method, or
- * <EM>partial</EM> such that this is not necessarily true. For
- * example, a case-sensitive dictionary order comparison of Strings
- * is total, but if it is case-insensitive it is partial, because
- * "abc" and "ABC" compare as equal even though "abc".equals("ABC")
- * returns false.
+/**
+ * Interface for objects that can be ordering among other objects. The
+ * ordering can be <em>total</em>, such that two objects only compare equal
+ * if they are also equal by the equals method, or <em>partial</em> such
+ * that this is not necessarily true. For example, a case-sensitive
+ * dictionary order comparison of Strings is total, but if it is
+ * case-insensitive it is partial, because "abc" and "ABC" compare as
+ * equal even though "abc".equals("ABC") returns false. However, if you use
+ * a partial ordering, it is a good idea to document your class as
+ * "inconsistent with equals", because the behavior of your class in a
+ * SortedMap will be different than in a HashMap.
+ *
+ * <p>Lists, arrays, and sets of objects that implement this interface can
+ * be sorted automatically, without the need for an explicit
+ * {@link Comparator}. Note that <code>e1.compareTo(null)</code> should
+ * throw an Exception; as should comparison between incompatible classes.
  *
  * @author Geoff Berry
  * @author Warren Levy <warrenl@cygnus.com>
- *
- * @since JDK1.2
- * @see java.util.Comparator
+ * @see Comparator
+ * @see Collections#sort(List)
+ * @see Arrays#sort(Object[])
+ * @see SortedSet
+ * @see SortedMap
+ * @see TreeSet
+ * @see TreeMap
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface Comparable
 {
   /**
-   * @return a negative integer if this object is less than
-   * <code>o<code>, zero if this object is equal to <code>o</code>, or
-   * a positive integer if this object is greater than <code>o</code>
+   * Compares this object with another, and returns a numerical result based
+   * on the comparison.  If the result is negative, this object sorts less
+   * than the other; if 0, the two are equal, and if positive, this object
+   * sorts greater than the other.  To translate this into boolean, simply
+   * perform <code>o1.compareTo(o2) <em>&lt;op&gt;</em> 0</code>, where op
+   * is one of &lt;, &lt;=, =, !=, &gt;, or &gt;=.
+   *
+   * <p>You must make sure that the comparison is mutual, ie.
+   * <code>sgn(x.compareTo(y)) == -sgn(y.compareTo(x))</code> (where sgn() is
+   * defined as -1, 0, or 1 based on the sign).  This includes throwing an
+   * exception in either direction if the two are not comparable; hence,
+   * <code>compareTo(null)</code> should always throw an Exception.
+   *
+   * <p>You should also ensure transitivity, in two forms:
+   * <code>x.compareTo(y) &gt; 0 && y.compareTo(z) &gt; 0</code> implies
+   * <code>x.compareTo(z) &gt; 0</code>; and <code>x.compareTo(y) == 0</code>
+   * implies <code>x.compareTo(z) == y.compareTo(z)</code>.
+   *
+   * @param o the object to be compared
+   * @return an integer describing the comparison
+   * @throws NullPointerException if o is null
+   * @throws ClassCastException if o cannot be compared
    */
-  int compareTo( Object o );
+  int compareTo(Object o);
 }
diff --git a/libjava/java/lang/Compiler.java b/libjava/java/lang/Compiler.java
index 28dd6b3..2d98811 100644
--- a/libjava/java/lang/Compiler.java
+++ b/libjava/java/lang/Compiler.java
@@ -1,6 +1,5 @@
-/* Compiler.java -- Interface for implementing a method to override 
-   Object.clone()comparaing objects to obtain an ordering
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* Compiler.java -- placeholder for Java-to-native runtime compilers
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +7,7 @@ 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
@@ -39,84 +38,91 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- */
-
 /**
- * The <code>Compiler</code> class is a place holder for a JIT
- * compiler implementation does nothing unless there is such a 
- * compiler by default.
- * <p>
- * The system property <code>java.compiler</code> may contain the name
+ * The <code>Compiler</code> class is a placeholder for a JIT compiler
+ * implementation, and does nothing unless there is such a compiler.
+ *
+ * <p>The system property <code>java.compiler</code> may contain the name
  * of a library to load with <code>System.loadLibrary</code> when the
- * virtual machine first starts.  If so and loading the library succeeds,
- * then a function by the name of <code>java_lang_Compiler_start()</code> 
+ * virtual machine first starts.  If so, and loading the library succeeds,
+ * then a function by the name of <code>java_lang_Compiler_start()</code>
  * in that library is called.
  *
- * Note that a VM might not have implemented any of this.
+ * <p>Note that a VM might not have implemented any of this.
  *
  * @author Tom Tromey <tromey@cygnus.com>
- *
+ * @see System#getProperty(String)
+ * @see System#getProperty(String, String)
+ * @see System#loadLibrary(String)
  * @since JDK 1.0
- * @see System#getProperty(java.lang.String)
- * @see System#getProperty(java.lang.String,java.lang.String)
- * @see System#loadLibrary(java.lang.String)
+ * @status updated to 1.4
  */
-public final class Compiler 
+public final class Compiler
 {
-    /**
-     * Don't allow new `Compiler's to be made.
-     */
-    private Compiler ()
-    {
-    }
+  /**
+   * Don't allow new `Compiler's to be made.
+   */
+  private Compiler()
+  {
+  }
+
+  /**
+   * Compile the class named by <code>oneClass</code>.
+   *
+   * @param oneClass the class to compile
+   * @return <code>false</code> if no compiler is available or
+   *         compilation failed, <code>true</code> if compilation succeeded
+   * @throws NullPointerException if oneClass is null
+   */
+  public static boolean compileClass(Class oneClass)
+  {
+    // Never succeed.
+    return false;
+  }
 
-    /**
-     * Compile the class named by <code>oneClass</code>.
-     * 
-     * @param oneClass the class to compile
-     * @return <code>false</code> if no compiler is available or 
-     * compilation failed and <code>true</code> if compilation succeeded.
-     */
-    public static boolean compileClass (Class oneClass) 
-    {
- 	// Never succeed.
-	return false;
-    }
-    
-    /**
-     * Compile the classes whose name matches <code>classNames/code>.
-     *
-     * @param classNames the name of classes to compile
-     * @return <code>false</code> if no compiler is available or 
-     * compilation failed and <code>true</code> if compilation succeeded.
-     */
-    public static boolean compileClasses (String classNames) 
-    {
-	// Note the incredibly lame interface.  Always fail.
-	return false;
-    }
+  /**
+   * Compile the classes whose name matches <code>classNames/code>.
+   *
+   * @param classNames the name of classes to compile
+   * @return <code>false</code> if no compiler is available or
+   *         compilation failed, <code>true</code> if compilation succeeded
+   * @throws NullPointerException if classNames is null
+   */
+  public static boolean compileClasses(String classNames)
+  {
+    // Note the incredibly lame interface.  Always fail.
+    return false;
+  }
 
-    /**
-     * This method examines the argument and performs an operation 
-     * according to the compilers documentation.  No specific operation
-     * is required.
-     */
-    public static Object command (Object arg) 
-    {
-	// Our implementation defines this to a no-op.
-	return null;
-    }
+  /**
+   * This method examines the argument and performs an operation
+   * according to the compilers documentation.  No specific operation
+   * is required.
+   *
+   * @param arg a compiler-specific argument
+   * @return a compiler-specific value, including null
+   * @throws NullPointerException if the compiler doesn't like a null arg
+   */
+  public static Object command(Object arg)
+  {
+    // Our implementation defines this to a no-op.
+    return null;
+  }
 
-    /**
-     * Calling <code>Compiler.enable()</code> will cause the compiler
-     * to resume operation if it was previously disabled.  
-     */
-    public static void enable () { }
+  /**
+   * Calling <code>Compiler.enable()</code> will cause the compiler
+   * to resume operation if it was previously disabled; provided that a
+   * compiler even exists.
+   */
+  public static void enable()
+  {
+  }
 
-    /**
-     * Calling <code>Compiler.disable()</code> will cause the compiler
-     * to be suspended.
-     */
-    public static void disable () { }
+  /**
+   * Calling <code>Compiler.disable()</code> will cause the compiler
+   * to be suspended; provided that a compiler even exists.
+   */
+  public static void disable()
+  {
+  }
 }
diff --git a/libjava/java/lang/Error.java b/libjava/java/lang/Error.java
index 76dd7de..8bb42dc 100644
--- a/libjava/java/lang/Error.java
+++ b/libjava/java/lang/Error.java
@@ -1,5 +1,5 @@
-/* Error.java - Indication of fatal abnormal conditions
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* Error.java -- Indication of fatal abnormal conditions
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,45 +38,70 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Applications should not try to catch errors since they indicate 
+ * Applications should not try to catch errors since they indicate
  * abnormal conditions.  An abnormal condition is something which should not
- * occur.  A few errors, like <code>ThreadDeath</code> error do normally
- * occur, but most applications should not catch it.  
- * <p>
- * A method is not required to declare any subclass of <code>Error</code> in 
+ * occur, or which should not be recovered from.  This latter category
+ * includes <code>ThreadDeath</code> and <code>AssertionError</code>.
+ *
+ * <p>A method is not required to declare any subclass of <code>Error</code> in
  * its <code>throws</code> clause which might be thrown but not caught while
- * executing the method..
+ * executing the method.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.0
+ * @status updated to 1.4
  */
 public class Error extends Throwable
 {
-  static final long serialVersionUID = 4980196508277280342L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 4980196508277280342L;
 
   /**
-   * Create an error without a message.
+   * Create an error without a message. The cause remains uninitialized.
+   *
+   * @see #initCause(Throwable)
    */
   public Error()
-    {
-      super();
-    }
+  {
+  }
 
   /**
-   * Create an error with a message.
+   * Create an error with a message. The cause remains uninitialized.
+   *
+   * @param s the message string
+   * @see #initCause(Throwable)
    */
   public Error(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
+
+  /**
+   * Create an error with a message and a cause.
+   *
+   * @param s the message string
+   * @param cause the cause of this error
+   * @since 1.4
+   */
+  public Error(String s, Throwable cause)
+  {
+    super(s, cause);
+  }
+
+  /**
+   * Create an error with a given cause, and a message of
+   * <code>cause == null ? null : cause.toString()</code>.
+   *
+   * @param cause the cause of this error
+   * @since 1.4
+   */
+  public Error(Throwable cause)
+  {
+    super(cause);
+  }
 }
diff --git a/libjava/java/lang/ExceptionInInitializerError.java b/libjava/java/lang/ExceptionInInitializerError.java
index f05a8ca..d04bdc0 100644
--- a/libjava/java/lang/ExceptionInInitializerError.java
+++ b/libjava/java/lang/ExceptionInInitializerError.java
@@ -1,5 +1,6 @@
-/* ExceptionInInitializerError.java 
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* ExceptionInInitializerError.java -- thrown when class initialization fails
+   with an uncaught exception
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +8,7 @@ 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
@@ -38,118 +39,85 @@ exception statement from your version. */
 
 package java.lang;
 
-import java.io.PrintStream;
-import java.io.PrintWriter;
-
-/* 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.
- */
-
 /**
- * An <code>ExceptionInInitializerError</code> is thrown when an 
- * unexpected exception has occurred in a static initializer or the
- * initializer for a static variable.
+ * An <code>ExceptionInInitializerError</code> is thrown when an uncaught
+ * exception has occurred in a static initializer or the initializer for a
+ * static variable. In general, this wraps only RuntimeExceptions, since the
+ * compiler does not allow a checked exception to be uncaught in an
+ * initializer. This exception only occurs during reflection, when a class
+ * is initialized as part of another action.
  *
- * @since JDK 1.1
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998 
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.1
+ * @status updated to 1.4
  */
 public class ExceptionInInitializerError extends LinkageError
 {
+  /**
+   * Compatible with JDK 1.1+.
+   */
   static final long serialVersionUID = 1521711792217232256L;
 
-  private Throwable exception = null;
+  /**
+   * The cause of this exception (duplicates the one stored in Throwable).
+   *
+   * @serial the exception cause
+   */
+  private final Throwable exception;
 
   /**
-   * Create an error without a message.
+   * Create an error without a message. The cause is initialized as null.
    */
   public ExceptionInInitializerError()
-    {
-      super();
-    }
+  {
+    this((String) null);
+  }
 
   /**
-   * Create an error with a message.
+   * Create an error with a message. The cause is initialized as null.
+   *
+   * @param s the message
    */
   public ExceptionInInitializerError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+    exception = null;
+  }
 
   /**
    * Creates an error an saves a reference to the <code>Throwable</code>
-   * object.
+   * object. The message string is null.
    *
    * @param t the exception thrown
    */
   public ExceptionInInitializerError(Throwable t)
-    {
-      super(t.toString());
-      exception = t;
-    }
-
-  /** 
-   * Return the exception that caused this error to be created.
-   * @return the stored <code>Throwable</code> object or <code>null</code>
-   * if this <code>ExceptionInInitializerError</code> has no stored
-   * <code>Throwable</code> object.
-   */
-  public Throwable getException()
-    {
-      return exception;
-    }
+  {
+    super(null);
+    initCause(t);
+    exception = t;
+  }
 
   /**
-   * Print a stack trace of the exception that occurred.
-   */
-  public void printStackTrace()
-    {
-      if (exception == null)
-	{
-	  super.printStackTrace();
-	}
-      else
-	{
-	  System.err.print(this.getClass() + ": ");
-	  exception.printStackTrace();
-	}
-    }
-
-  /**
-   * Print a stack trace of the exception that occurred to 
-   * the specified <code>PrintStream</code>.
+   * Return the exception that caused this error to be created. This is a
+   * legacy method; the preferred choice now is {@link Throwable#getCause()}.
+   *
+   * @return the cause, or null if unknown
    */
-  public void printStackTrace(PrintStream ps)
-    {
-      if (exception == null)
-	{
-	  super.printStackTrace(ps);
-	}
-      else
-	{
-	  ps.print(this.getClass() + ": ");
-	  exception.printStackTrace(ps);
-	}
-    }
+  public Throwable getException()
+  {
+    return exception;
+  }
 
   /**
-   * Print a stack trace of the exception that occurred to 
-   * the specified <code>PrintWriter</code>.
+   * Return the exception that cause this error to be created.
+   *
+   * @return the cause, or null if unknown
+   * @since 1.4
    */
-  public void printStackTrace(PrintWriter pw)
-    {
-      if (exception == null)
-	{
-	  super.printStackTrace(pw);
-	}
-      else
-	{
-	  pw.print(this.getClass() + ": ");
-	  exception.printStackTrace(pw);
-	}
-    }
+  public Throwable getCause()
+  {
+    return exception;
+  }
 }
diff --git a/libjava/java/lang/IllegalAccessError.java b/libjava/java/lang/IllegalAccessError.java
index b672478..a5c384e 100644
--- a/libjava/java/lang/IllegalAccessError.java
+++ b/libjava/java/lang/IllegalAccessError.java
@@ -1,5 +1,5 @@
-/* IllegalAccessError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalAccessError.java -- thrown when linking to an inaccessible member
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,43 +38,39 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
- * An <code>IllegalAccessError</code> is thrown when an attempt is made to 
+ * An <code>IllegalAccessError</code> is thrown when an attempt is made to
  * call a method, or access or modify a field that the application does not
- * have access to.  Because this error is usually caught by a compiler, 
+ * have access to.  Because this error is usually caught by a compiler,
  * the error only occurs at runtime when the definition of a class has
- * changed in a way that is incompatible with the previously compiled 
+ * changed in a way that is incompatible with the previously compiled
  * application.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class IllegalAccessError extends IncompatibleClassChangeError
 {
-  static final long serialVersionUID = -8988904074992417891L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -8988904074992417891L;
 
   /**
    * Create an error without a message.
    */
   public IllegalAccessError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public IllegalAccessError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/IllegalAccessException.java b/libjava/java/lang/IllegalAccessException.java
index 1bef5e8..f6fc8f6 100644
--- a/libjava/java/lang/IllegalAccessException.java
+++ b/libjava/java/lang/IllegalAccessException.java
@@ -1,6 +1,6 @@
-/* IllegalAccessException.java -- exception thrown when trying to load a 
-   class that is not public and in another package.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalAccessException.java -- thrown on attempt to reflect on
+   inaccessible data
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,45 +39,57 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Thrown in two cases.  The first is when try to load a class that is
- * not public and in another package using specific methods from 
- * <code>ClassLoader</code> and <code>Class</code>.  The second case is
- * when trying to create a new instance of a class to which you do not have
- * access to the zero argument constructor as in using the 
- * <code>newsInstance</code> method of class <code>Class</code>.
+ * Thrown whenever a reflective method tries to do something that the
+ * compiler would not allow.  For example, using reflection to set a private
+ * variable that belongs to a class in another package is bad.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @see Class#newInstance()
+ * @see Field#set(Object, Object)
+ * @see Field#setBoolean(Object, boolean)
+ * @see Field#setByte(Object, byte)
+ * @see Field#setShort(Object, short)
+ * @see Field#setChar(Object, char)
+ * @see Field#setInt(Object, int)
+ * @see Field#setLong(Object, long)
+ * @see Field#setFloat(Object, float)
+ * @see Field#setDouble(Object, double)
+ * @see Field#get(Object)
+ * @see Field#getBoolean(Object)
+ * @see Field#getByte(Object)
+ * @see Field#getShort(Object)
+ * @see Field#getChar(Object)
+ * @see Field#getInt(Object)
+ * @see Field#getLong(Object)
+ * @see Field#getFloat(Object)
+ * @see Field#getDouble(Object)
+ * @see Method#invoke(Object, Object[])
+ * @see Constructor#newInstance(Object[])
+ * @status updated to 1.4
  */
 public class IllegalAccessException extends Exception
 {
-  static final long serialVersionUID = 6616958222490762034L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 6616958222490762034L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalAccessException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalAccessException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/IllegalArgumentException.java b/libjava/java/lang/IllegalArgumentException.java
index 6d5e312..deb6735 100644
--- a/libjava/java/lang/IllegalArgumentException.java
+++ b/libjava/java/lang/IllegalArgumentException.java
@@ -1,6 +1,6 @@
-/* IllegalArgumentException.java -- exception may be thrown when a method
-   is passed an illegal or inappropriate argument.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalArgumentException.java -- thrown when a method is passed an
+   illegal or inappropriate argument
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -38,41 +38,38 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * When a method is passed an illegal or inappropriate argument 
- * this exception may be thrown.
+ * Thrown when a method is passed an illegal or inappropriate argument. For
+ * example:<br>
+ * <pre>
+ * wait(-1);
+ * </pre>
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class IllegalArgumentException extends RuntimeException
 {
-  static final long serialVersionUID = -5365630128856068164L;
-  
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -5365630128856068164L;
+
   /**
    * Create an exception without a message.
    */
   public IllegalArgumentException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalArgumentException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/IllegalMonitorStateException.java b/libjava/java/lang/IllegalMonitorStateException.java
index c556be7..08e1ba7 100644
--- a/libjava/java/lang/IllegalMonitorStateException.java
+++ b/libjava/java/lang/IllegalMonitorStateException.java
@@ -1,6 +1,6 @@
-/* IllegalMonitorStateException.java -- exception thrown when a thread 
-   attempts to wait on an object's monitor.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalMonitorStateException.java -- thrown when trying to wait or
+   notify a monitor that is not owned
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,43 +39,40 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * If a thread attempts to wait on an object's monitor then
- * <code>IllegalMonitorStateException</code> can be thrown.  This
- * exception is also thrown to give a message to other threads also waiting
- * on an object's monitor without owning the monitor.
+ * Thrown when a thread attempts to wait or notify on a monitor that it
+ * does not own (ie. it has not synchronized on the object). For example:<br>
+ * <pre>
+ * void m() {
+ *   notify();
+ * }
+ * </pre>
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class IllegalMonitorStateException extends RuntimeException
 {
-  static final long serialVersionUID = 3713306369498869069L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 3713306369498869069L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalMonitorStateException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalMonitorStateException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/IllegalStateException.java b/libjava/java/lang/IllegalStateException.java
index df759f1..16dcf1a 100644
--- a/libjava/java/lang/IllegalStateException.java
+++ b/libjava/java/lang/IllegalStateException.java
@@ -1,6 +1,6 @@
-/* IllegalStateException.java -- exception thrown when invoking a method at
-   an illegal or inappropriate time.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalStateException.java -- thrown when invoking a method at
+   an illegal or inappropriate time
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,41 +39,42 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Invoking a method at an illegal or inappropriate time can result
- * in an <code>IllegalStateException</code>.
+ * Thrown when a method is invoked at an illegal or inappropriate time. For
+ * example:<br>
+ * <pre>
+ * void m(Collecion c)
+ * {
+ *   c.iterator().remove();
+ * }
+ * </pre>
  *
- * @since JDK 1.1
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @since 1.1
+ * @status updated to 1.4
  */
 public class IllegalStateException extends RuntimeException
 {
-  static final long serialVersionUID = -1848914673093119416L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = -1848914673093119416L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalStateException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalStateException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/IllegalThreadStateException.java b/libjava/java/lang/IllegalThreadStateException.java
index 37d91ed..bcc188e 100644
--- a/libjava/java/lang/IllegalThreadStateException.java
+++ b/libjava/java/lang/IllegalThreadStateException.java
@@ -1,7 +1,6 @@
-/* IllegalThreadStateException.java -- exception thrown when trying to
-   suspend or resume a Thread when it is not in an appropriate state
-   for the operation.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalThreadStateException.java -- thrown when trying to manipulate a
+   Thread when it is not in an appropriate state
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -9,7 +8,7 @@ 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
@@ -40,41 +39,37 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * When trying to <code>suspend</code> or <code>resume</code> an object
- * of class <code>Thread</code> when it is not in an appropriate state
- * for the operation.
+ * Thrown When trying to manipulate a Thread which is in an inappropriate
+ * state. Since the documentation suggests that this can happen with
+ * <code>Thread.suspend</code> or <code>Thread.resume</code>, but these
+ * two methods are deprecated, this exception is likely very rare.
  *
- * @since JDK 1.0
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class IllegalThreadStateException extends IllegalArgumentException
 {
-  static final long serialVersionUID = -7626246362397460174L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -7626246362397460174L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalThreadStateException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalThreadStateException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/IncompatibleClassChangeError.java b/libjava/java/lang/IncompatibleClassChangeError.java
index 48781b7..7f569fd 100644
--- a/libjava/java/lang/IncompatibleClassChangeError.java
+++ b/libjava/java/lang/IncompatibleClassChangeError.java
@@ -1,5 +1,5 @@
-/* IncompatibleClassChangeError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IncompatibleClassChangeError.java -- thrown for binary incompatible classes
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,40 +38,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
- * An <code>IncompatibleClassChangeError</code> is thrown when the 
- * definition of a class used by the currently executing method has
- * changed in an incompatible way.
+ * An <code>IncompatibleClassChangeError</code> is thrown when the definition
+ * of a class used by the currently executing method has changed in an
+ * incompatible way.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class IncompatibleClassChangeError extends LinkageError
 {
-  static final long serialVersionUID = -4914975503642802119L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4914975503642802119L;
 
   /**
    * Create an error without a message.
    */
   public IncompatibleClassChangeError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public IncompatibleClassChangeError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/IndexOutOfBoundsException.java b/libjava/java/lang/IndexOutOfBoundsException.java
index f93814a..336f872 100644
--- a/libjava/java/lang/IndexOutOfBoundsException.java
+++ b/libjava/java/lang/IndexOutOfBoundsException.java
@@ -1,7 +1,5 @@
-/* IndexOutOfBoundsException.java -- exception thrown when attempting to 
-   access an index which is out of bounds on objects like String, Array,
-   or Vector.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IndexOutOfBoundsException.java -- thrown for an invalid index
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -9,7 +7,7 @@ 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
@@ -40,44 +38,38 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * This exception can be thrown to indicate an attempt to access an
  * index which is out of bounds on objects like String, Array, or Vector.
  * Usually any negative integer less than or equal to -1 and positive 
  * integer greater than or equal to the size of the object is an index
  * which would be out of bounds.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class IndexOutOfBoundsException extends RuntimeException
 {
-  static final long serialVersionUID = 234122996006267687L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 234122996006267687L;
 
   /**
    * Create an exception without a message.
    */
   public IndexOutOfBoundsException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IndexOutOfBoundsException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/InheritableThreadLocal.java b/libjava/java/lang/InheritableThreadLocal.java
index 2dc85f7..31b64f5 100644
--- a/libjava/java/lang/InheritableThreadLocal.java
+++ b/libjava/java/lang/InheritableThreadLocal.java
@@ -1,5 +1,5 @@
-/* java.lang.InheritableThreadLocal
-   Copyright (C) 2000, 2001 Free Software Foundation, Inc.
+/* InheritableThreadLocal -- a ThreadLocal which inherits values across threads
+   Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,141 +38,102 @@ exception statement from your version. */
 package java.lang;
 
 import java.util.Iterator;
-import java.util.HashSet;
-import java.util.Map;
-import java.util.Set;
+import java.util.List;
+import java.util.ArrayList;
 import java.util.WeakHashMap;
 
 /**
- * ThreadLocal whose value is inherited by child Threads.
- * The value of the InheritableThreadLocal associated with the (parent) Thread
- * on the moment that it creates a new (child) Thread is set as the value that
- * is associated with the new (child) Thread.
- * <p>
- * It is possible to make the value associated with the child Thread a function
- * of the value that is associated with the parent Thread by overriding the
- * <code>childValue()</code> method.
+ * A ThreadLocal whose value is inherited by child Threads. The value of the
+ * InheritableThreadLocal associated with the (parent) Thread is copied to
+ * the new (child) Thread at the moment of creation.
+ *
+ * <p>It is possible to make the value associated with the child Thread a
+ * function of the value that is associated with the parent Thread by
+ * overriding the <code>childValue()</code> method. The utility of this class
+ * is in transferring items like User ID or Transaction ID across threads
+ * automatically.
  *
+ * @author Mark Wielaard <mark@klomp.org>
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see ThreadLocal
  * @since 1.2
- * @author Mark Wielaard (mark@klomp.org)
+ * @status updated to 1.4
  */
-public class InheritableThreadLocal extends ThreadLocal {
-	
-	/**
-	 * Maps Threads to a Set of InheritableThreadLocals
-	 * (the heritage of that Thread).
-	 * Uses a WeakHashMap so if the Thread is garbage collected the reference
-	 * to that Set disappears.
-	 * Both <code>AddToHeritage</code> access and modify it so they have to
-	 * synchronize on the threadMap when they do.
-	 */
-	private static Map threadMap = new WeakHashMap();
-	
-	/**
-	 * Creates a new InheritableThreadLocal that has no values associated
-	 * with it yet.
-	 */
-	public InheritableThreadLocal() {
-		super();
-	}
-	
-	/**
-	 * Determines the value associated with a newly created child Thread
-	 * as a function of the value associated with the currently executing
-	 * (parent) Thread.
-	 * <p>
-	 * The default implementation just returns the parentValue.
-	 */
-	protected Object childValue(Object parentValue) {
-		return parentValue;
-	}
-	
-	/**
-	 * Adds this <code>InheritableThreadLocal</code> to the heritage of the
-	 * current Thread and returns the value of the <code>ThreadLocal</code>
-	 * for the Thread. The value will be either the last value that the
-	 * current Thread has set, or the childValue of the last value that the
-	 * parent Thread set before the current Thread was created, or the
-	 * initialValue of the <code>ThreadLocal</code>.
-	 *
-	 * @see ThreadLocal#get()
-	 */
-	public Object get() {
-		addToHeritage(); 
-		return super.get();
-	}
-	
-	/**
-	 * Adds this <code>InheritableThreadLocal</code> to the heritage of the
-	 * current Thread and sets the value of the <code>ThreadLocal</code>
-	 * for the Thread.
-	 *
-	 * @see ThreadLocal#set(Object)
-	 */
-	public void set(Object value) {
-		addToHeritage();
-		super.set(value);
-	}
-	
-	/**
-	 * Adds this <code>InheritableThreadLocal</code> to the heritage
-	 * of the current Thread.
-	 */
-	private void addToHeritage() {
-		Thread currentThread = Thread.currentThread();
-		Set heritage;
-		synchronized(threadMap) {
-			heritage = (Set)threadMap.get(currentThread);
-		}
-		// Note that we don't have to synchronize on the heritage Set
-		// since only this Thread (or the parent Thread when creating
-		// the heritage) ever modifies it.
-		if (heritage == null) {
-			heritage = new HashSet();
-			synchronized(threadMap) {
-				threadMap.put(currentThread, heritage);
-			}
-		}
-		if (!heritage.contains(this)) {
-			heritage.add(this);
-		}
-	}
-	
-	/**
-	 * Generates the childValues of all <code>InheritableThreadLocal</code>s
-	 * that are in the heritage of the current Thread for the newly created
-	 * childThread.
-	 * Should be called from the contructor of java.lang.Thread.
-	 */
-	static void newChildThread(Thread childThread) {
-		// The currentThread is the parent of the new thread
-		Thread parentThread = Thread.currentThread();
-		
-		// Inherit all the InheritableThreadLocals of the parent thread
-		Set heritage;
-		synchronized(threadMap) {
-			heritage = (Set)threadMap.get(parentThread);
-		}
-		// Note that we don't have to synchronize on the heritage Set
-		// since only this Thread (or the parent Thread when creating
-		// the heritage) ever modifies it.
-		if (heritage != null) {
-			synchronized(threadMap) {
-				threadMap.put(childThread, new HashSet(heritage));
-			}
-			// And constructs all the new child values
-			// (has to be done now that we are executing in the parentThread)
-			Iterator it = heritage.iterator();
-			while (it.hasNext()) {
-				InheritableThreadLocal local =
-					(InheritableThreadLocal) it.next();
-				// Note that the parentValue cannot be null
-				// If it was it would not be in the heritage
-				Object parentValue = local.get(parentThread).getValue();
-				Object childValue = local.childValue(parentValue);
-				ThreadLocal.Value v = new ThreadLocal.Value(childValue);
-				local.set(childThread, v);
-			}
-		}
-	}
+public class InheritableThreadLocal extends ThreadLocal
+{
+  /**
+   * Maps Threads to a List of InheritableThreadLocals (the heritage of that
+   * Thread). Uses a WeakHashMap so if the Thread is garbage collected the
+   * List can be collected, too. Maps to a list in case the user overrides
+   * equals.
+   */
+  private static final WeakHashMap threadMap = new WeakHashMap();
+
+  /**
+   * Creates a new InheritableThreadLocal that has no values associated
+   * with it yet.
+   */
+  public InheritableThreadLocal()
+  {
+    Thread currentThread = Thread.currentThread();
+    // Note that we don't have to synchronize, as only this thread will
+    // ever modify the returned heritage.
+    List heritage = (List) threadMap.get(currentThread);
+    if (heritage == null)
+      {
+        heritage = new ArrayList();
+        threadMap.put(currentThread, heritage);
+      }
+    heritage.add(this);
+  }
+
+  /**
+   * Determines the value associated with a newly created child Thread as a
+   * function of the value associated with the currently executing (parent)
+   * Thread. The default implementation just returns the parentValue.
+   *
+   * @param parentValue the value of this object in the parent thread at
+   *        the moment of creation of the child
+   * @return the initial value for the child thread
+   */
+  protected Object childValue(Object parentValue)
+  {
+    return parentValue;
+  }
+
+  /**
+   * Generates the childValues of all <code>InheritableThreadLocal</code>s
+   * that are in the heritage of the current Thread for the newly created
+   * childThread. Should be called from the contructor Thread.
+   *
+   * @param childThread the newly created thread, to inherit from this thread
+   * @see Thread#Thread(ThreadGroup, Runnable, String)
+   */
+  static void newChildThread(Thread childThread)
+  {
+    // The currentThread is the parent of the new thread.
+    Thread parentThread = Thread.currentThread();
+    // Note that we don't have to synchronize, as only this thread will
+    // ever modify the returned heritage.
+    ArrayList heritage = (ArrayList) threadMap.get(parentThread);
+    if (heritage != null)
+      {
+        threadMap.put(childThread, heritage.clone());
+        // Perform the inheritance.
+        Iterator it = heritage.iterator();
+        int i = heritage.size();
+        while (--i >= 0)
+          {
+            InheritableThreadLocal local = (InheritableThreadLocal) it.next();
+            Object parentValue = local.valueMap.get(parentThread);
+            if (parentValue != null)
+              {
+                Object childValue = local.childValue(parentValue == NULL
+                                                     ? null : parentValue);
+                local.valueMap.put(childThread, (childValue == null
+                                                 ? NULL : parentValue));
+              }
+          }
+      }
+  }
 }
diff --git a/libjava/java/lang/InstantiationError.java b/libjava/java/lang/InstantiationError.java
index 9b9f07b..54aa7b3 100644
--- a/libjava/java/lang/InstantiationError.java
+++ b/libjava/java/lang/InstantiationError.java
@@ -1,5 +1,5 @@
-/* InstantiationError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* InstantiationError.java -- thrown when the linker cannot create an instance
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,43 +38,38 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
- * An <code>InstantiationError</code> is thrown when an attempt is made to 
- * create an instance of an abstract class or an interface.  Because this 
- * error is usually caught by a compiler, 
- * the error only occurs at runtime when the definition of a class has
- * changed in a way that is incompatible with the previously compiled 
- * application.
+ * An <code>InstantiationError</code> is thrown when an attempt is made to
+ * create an instance of an abstract class or an interface.  Because this
+ * error is usually caught by a compiler, the error only occurs at runtime
+ * when the definition of a class has changed in a way that is incompatible
+ * with the previously compiled application.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class InstantiationError extends IncompatibleClassChangeError
 {
-  static final long serialVersionUID = -4885810657349421204L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4885810657349421204L;
 
   /**
    * Create an error without a message.
    */
   public InstantiationError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public InstantiationError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/InstantiationException.java b/libjava/java/lang/InstantiationException.java
index d6d4adf..5114814 100644
--- a/libjava/java/lang/InstantiationException.java
+++ b/libjava/java/lang/InstantiationException.java
@@ -1,6 +1,6 @@
-/* InstantiationException.java -- exception thrown when trying to instantiate
-   interfaces and abstract classes using Class.newInstance.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* InstantiationException.java -- thrown when reflection cannot create an
+   instance
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,42 +39,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.
- * Interfaces and abstract classes cannot be instantiated using the 
- * <code>newInstance</code> method of class <code>Class</code>.  Trying
- * to do so results in this exception being thrown.
+ * Thrown when an attempt is made to use reflection to build a
+ * non-instantiable class (an interface or abstract class).
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @see Class#newInstance()
+ * @status updated to 1.4
  */
 public class InstantiationException extends Exception
 {
-  static final long serialVersionUID = -8441929162975509110L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -8441929162975509110L;
 
   /**
    * Create an exception without a message.
    */
   public InstantiationException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public InstantiationException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/InternalError.java b/libjava/java/lang/InternalError.java
index 92361ed..d85aed1 100644
--- a/libjava/java/lang/InternalError.java
+++ b/libjava/java/lang/InternalError.java
@@ -1,5 +1,5 @@
-/* InternalError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* InternalError.java -- thrown when the VM encounters an internal error
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,39 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
  * An <code>InternalError</code> is thrown when a mystical error has
  * occurred in the Java Virtual Machine.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class InternalError extends VirtualMachineError
 {
-  static final long serialVersionUID = -9062593416125562365L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -9062593416125562365L;
 
   /**
    * Create an error without a message.
    */
   public InternalError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public InternalError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/InterruptedException.java b/libjava/java/lang/InterruptedException.java
index 6af9d75..2ee7867 100644
--- a/libjava/java/lang/InterruptedException.java
+++ b/libjava/java/lang/InterruptedException.java
@@ -1,7 +1,5 @@
-/* InterruptedException.java -- exception thrown when a thread interrupts 
-   another thread which was previously sleeping, waiting, or paused in some 
-   other way.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* InterruptedException.java -- thrown when a thread is interrupted
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -9,7 +7,7 @@ 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
@@ -40,42 +38,43 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.
- * Thrown when a thread interrupts another thread which was previously 
- * sleeping, waiting, or paused in some other way.  See the 
+ * Thrown when a thread interrupts another thread which was previously
+ * sleeping, waiting, or paused in some other way.  See the
  * <code>interrupt</code> method of class <code>Thread</code>.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @see Object#wait()
+ * @see Object#wait(long)
+ * @see Object#wait(long, int)
+ * @see Thread#sleep(long)
+ * @see Thread#interrupt()
+ * @see Thread#interrupted()
+ * @status updated to 1.4
  */
 public class InterruptedException extends Exception
 {
-  static final long serialVersionUID = 6700697376100628473L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 6700697376100628473L;
 
   /**
    * Create an exception without a message.
    */
   public InterruptedException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   *
+   * @param s the message
    */
   public InterruptedException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/LinkageError.java b/libjava/java/lang/LinkageError.java
index a5c91ca..020fe0a 100644
--- a/libjava/java/lang/LinkageError.java
+++ b/libjava/java/lang/LinkageError.java
@@ -1,5 +1,6 @@
-/* LinkageError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* LinkageError.java -- thrown when classes valid at separate compile times
+   cannot be linked to each other
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +8,7 @@ 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
@@ -38,40 +39,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
- * Subclasses of <code>LinkageError</code> are thrown to indicate 
- * a class which is depended upon by another class has incompatibly 
- * changed after the compilation of the latter class.
+ * Subclasses of <code>LinkageError</code> are thrown to indicate that two
+ * classes which were compatible at separate compilation times cannot be
+ * linked to one another.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class LinkageError extends Error
 {
-  static final long serialVersionUID = 3579600108157160122L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 3579600108157160122L;
 
   /**
    * Create an error without a message.
    */
   public LinkageError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public LinkageError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/NegativeArraySizeException.java b/libjava/java/lang/NegativeArraySizeException.java
index f564233..ee73a97 100644
--- a/libjava/java/lang/NegativeArraySizeException.java
+++ b/libjava/java/lang/NegativeArraySizeException.java
@@ -1,6 +1,6 @@
-/* NegativeArraySizeException.java -- exception thrown when an attempt is 
-   made to create an array with a negative size.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NegativeArraySizeException.java -- thrown on attempt to create array
+   with a negative size
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,41 +39,39 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * Thrown when an attempt is made to create an array with a negative
- * size.
+ * size. For example:<br>
+ * <pre>
+ * int i = -1;
+ * int[] array = new int[i];
+ * </pre>
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class NegativeArraySizeException extends RuntimeException
 {
-  static final long serialVersionUID = -8960118058596991861L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -8960118058596991861L;
 
   /**
    * Create an exception without a message.
    */
   public NegativeArraySizeException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NegativeArraySizeException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/NoClassDefFoundError.java b/libjava/java/lang/NoClassDefFoundError.java
index 2e75b65..5ca69bc 100644
--- a/libjava/java/lang/NoClassDefFoundError.java
+++ b/libjava/java/lang/NoClassDefFoundError.java
@@ -1,5 +1,5 @@
-/* NoClassDefFoundError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoClassDefFoundError.java -- thrown when a ClassLoader cannot find a class
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,43 +38,39 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
  * A <code>NoClassDefFoundError</code> is thrown when a classloader or the
  * Java Virtual Machine tries to load a class and no definition of the class
  * can be found.  This could happen when using the <code>new</code> expression
- * or during a normal method call.  The reason this would occur at runtime is 
+ * or during a normal method call.  The reason this would occur at runtime is
  * because the missing class definition existed when the currently executing 
  * class was compiled, but now that definition cannot be found.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class NoClassDefFoundError extends LinkageError
 {
-  static final long serialVersionUID = 9095859863287012458L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 9095859863287012458L;
 
   /**
    * Create an error without a message.
    */
   public NoClassDefFoundError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public NoClassDefFoundError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/NoSuchFieldError.java b/libjava/java/lang/NoSuchFieldError.java
index 66eb66a..0a197b0 100644
--- a/libjava/java/lang/NoSuchFieldError.java
+++ b/libjava/java/lang/NoSuchFieldError.java
@@ -1,5 +1,5 @@
-/* NoSuchFieldError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoSuchFieldError.java -- thrown when the linker does not find a field
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,40 +38,37 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
  * A <code>NoSuchFieldError</code> is thrown if an application attempts
- * to access the field of an object and that object no longer has that 
- * field.  
+ * to access a field of a class, and that class no longer has that field.
+ * This is normally detected by the compiler, so it signals that you are
+ * using binary incompatible class versions.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class NoSuchFieldError extends IncompatibleClassChangeError
 {
-  static final long serialVersionUID = -3456430195886129035L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -3456430195886129035L;
 
   /**
    * Create an error without a message.
    */
   public NoSuchFieldError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public NoSuchFieldError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/NoSuchFieldException.java b/libjava/java/lang/NoSuchFieldException.java
index 596371c..ee721eb 100644
--- a/libjava/java/lang/NoSuchFieldException.java
+++ b/libjava/java/lang/NoSuchFieldException.java
@@ -1,6 +1,5 @@
-/* NoSuchFieldException.java -- exception thrown to indicate the class does
-   not have the specified field.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoSuchFieldException.java -- thrown when reflecting a non-existant field
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +7,7 @@ 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
@@ -39,40 +38,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Thrown to indicate the class does not have the specified field.
+ * Thrown to indicate the class does not have the specified field. This is
+ * caused by a variety of reflection methods, when looking up a field by name.
  *
- * @since JDK 1.1
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @since 1.1
+ * @status updated to 1.4
  */
 public class NoSuchFieldException extends Exception
 {
-  static final long serialVersionUID = -6143714805279938260L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = -6143714805279938260L;
 
   /**
    * Create an exception without a message.
    */
   public NoSuchFieldException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NoSuchFieldException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/NoSuchMethodError.java b/libjava/java/lang/NoSuchMethodError.java
index 1a219ef..dced018 100644
--- a/libjava/java/lang/NoSuchMethodError.java
+++ b/libjava/java/lang/NoSuchMethodError.java
@@ -1,5 +1,5 @@
-/* NoSuchMethodError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoSuchMethodError.java -- thrown when the linker does not find a method
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,40 +38,37 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
  * A <code>NoSuchMethodError</code> is thrown if an application attempts
- * to access a method of a class, and that class no longer has that 
- * method.  
+ * to access a method of a class, and that class no longer has that method.
+ * This is normally detected by the compiler, so it signals that you are
+ * using binary incompatible class versions.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class NoSuchMethodError extends IncompatibleClassChangeError
 {
+  /**
+   * Compatible with JDK 1.0+.
+   */
   static final long serialVersionUID = -3765521442372831335L;
 
   /**
    * Create an error without a message.
    */
   public NoSuchMethodError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public NoSuchMethodError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/NoSuchMethodException.java b/libjava/java/lang/NoSuchMethodException.java
index eb4a7c1..cba6920 100644
--- a/libjava/java/lang/NoSuchMethodException.java
+++ b/libjava/java/lang/NoSuchMethodException.java
@@ -1,6 +1,5 @@
-/* NoSuchMethodException.java -- exception thrown to indicate the class
-   does not have the specified method.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoSuchMethodException.java -- thrown when reflecting a non-existant method
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +7,7 @@ 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
@@ -39,40 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Thrown to indicate the class does not have the specified method.
+ * Thrown to indicate the class does not have the specified method. This is
+ * caused by a variety of reflection methods, when looking up a method by name.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class NoSuchMethodException extends Exception
 {
-  static final long serialVersionUID = 5034388446362600923L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 5034388446362600923L;
 
   /**
    * Create an exception without a message.
    */
   public NoSuchMethodException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NoSuchMethodException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/NullPointerException.java b/libjava/java/lang/NullPointerException.java
index 32ae6ef..bab2071 100644
--- a/libjava/java/lang/NullPointerException.java
+++ b/libjava/java/lang/NullPointerException.java
@@ -1,6 +1,5 @@
-/* NullPointerException.java -- exception thrown when attempting to use null
-   where an object is required.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NullPointerException.java -- thrown when using null instead of an object
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +7,7 @@ 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
@@ -39,41 +38,45 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * Thrown when attempting to use <code>null</code> where an object
- * is required, such as when accessing an instance method of a null object.
+ * is required. The Virtual Machine automatically throws this exception
+ * for the following:<br><ul>
+ * <li>Calling an instance method on a null object</li>
+ * <li>Accessing or modifying a field of a null object</li>
+ * <li>Taking the array length of a null array</li>
+ * <li>Accessing or modifying the slots of a null array</li>
+ * <li>Throwing a null Throwable</li>
+ * <li>Synchronizing on a null object</li>
+ * </ul>
+ * <p>Applications should also throw NullPointerExceptions whenever
+ * <code>null</code> is an inappropriate parameter to a method.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class NullPointerException extends RuntimeException
 {
-  static final long serialVersionUID = 5162710183389028792L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 5162710183389028792L;
 
   /**
    * Create an exception without a message.
    */
   public NullPointerException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NullPointerException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/NumberFormatException.java b/libjava/java/lang/NumberFormatException.java
index be637ad..d076cc8 100644
--- a/libjava/java/lang/NumberFormatException.java
+++ b/libjava/java/lang/NumberFormatException.java
@@ -1,6 +1,5 @@
-/* NumberFormatException.java -- exception may be thrown when attempting to
-   convert a String to one of the numeric types, but the operation fails.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NumberFormatException.java -- thrown when parsing a bad string as a number
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +7,7 @@ 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
@@ -39,42 +38,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Can be thrown when attempting to convert a <code>String</code> to 
+ * Can be thrown when attempting to convert a <code>String</code> to
  * one of the numeric types, but the operation fails because the string
  * has the wrong format.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class NumberFormatException extends IllegalArgumentException
 {
-  static final long serialVersionUID = -2848938806368998894L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -2848938806368998894L;
 
   /**
    * Create an exception without a message.
    */
   public NumberFormatException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NumberFormatException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/OutOfMemoryError.java b/libjava/java/lang/OutOfMemoryError.java
index b6a52ac..b56b8f4 100644
--- a/libjava/java/lang/OutOfMemoryError.java
+++ b/libjava/java/lang/OutOfMemoryError.java
@@ -1,5 +1,5 @@
-/* OutOfMemoryError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* OutOfMemoryError.java -- thrown when a memory allocation fails
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,40 +38,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
- * When the Java Virtual Machine is unable to allocate an object because it 
- * is out of memory and no more memory could be made available by the 
- * garbage collector an <code>OutOfMemoryError</code> is thrown.
+ * Thrown when the Java Virtual Machine is unable to allocate an object
+ * because it is out of memory and no more memory could be made available
+ * by the garbage collector.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class OutOfMemoryError extends VirtualMachineError
 {
-  static final long serialVersionUID = 8228564086184010517L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 8228564086184010517L;
 
   /**
    * Create an error without a message.
    */
   public OutOfMemoryError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public OutOfMemoryError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/Process.java b/libjava/java/lang/Process.java
index d8c5da5..e5df417 100644
--- a/libjava/java/lang/Process.java
+++ b/libjava/java/lang/Process.java
@@ -1,5 +1,5 @@
-/* Process.java - Represent spawned system process.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* Process.java - Represent spawned system process
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -41,71 +41,83 @@ package java.lang;
 import java.io.OutputStream;
 import java.io.InputStream;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- */
-
 /**
  * An instance of a subclass of <code>Process</code> is created by the
  * <code>Runtime.exec</code> methods.  Methods in <code>Process</code>
- * provide a means to send input to a process, obtain the output from a 
- * subprocess, destroy a subprocess, obtain the exit value from a 
+ * provide a means to send input to a process, obtain the output from a
+ * subprocess, destroy a subprocess, obtain the exit value from a
  * subprocess, and wait for a subprocess to complete.
- * 
- * @since JDK 1.0
- * 
+ *
+ * <p>This is dependent on the platform, and some processes (like native
+ * windowing processes, 16-bit processes in Windows, or shell scripts) may
+ * be limited in functionality. Because some platforms have limited buffers
+ * between processes, you may need to provide input and read output to prevent
+ * the process from blocking, or even deadlocking.
+ *
+ * <p>Even if all references to this object disapper, the process continues
+ * to execute to completion. There are no guarantees that the
+ * subprocess execute asynchronously or concurrently with the process which
+ * owns this object.
+ *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
+ * @see Runtime#exec(String[], String[], File)
+ * @since 1.0
+ * @status updated to 1.4
  */
 public abstract class Process
 {
   /**
    * Empty constructor does nothing.
    */
-  public Process() { }
+  public Process()
+  {
+  }
 
   /**
-   * Obtain the output stream of the subprocess.  It may help to 
-   * associate this stream as the redirected STDIN file descriptor of
-   * the subprocess.
+   * Obtain the output stream that sends data to the subprocess. This is
+   * the STDIN of the subprocess. When implementing, you should probably
+   * use a buffered stream.
+   *
+   * @return the output stream that pipes to the process input
    */
   public abstract OutputStream getOutputStream();
 
   /**
-   * Obtain the input stream of the subprocess.  It may help to 
-   * associate this stream as the redirected STDOUT file descriptor of
-   * the subprocess.
+   * Obtain the input stream that receives data from the subprocess. This is
+   * the STDOUT of the subprocess. When implementing, you should probably
+   * use a buffered stream.
+   *
+   * @return the input stream that pipes data from the process output
    */
   public abstract InputStream getInputStream();
 
   /**
-   * Obtain the error input stream of the subprocess.  It may help to 
-   * associate this stream as the redirected STDERR file descriptor of
-   * the subprocess.
+   * Obtain the input stream that receives data from the subprocess. This is
+   * the STDERR of the subprocess. When implementing, you should probably
+   * use a buffered stream.
+   *
+   * @return the input stream that pipes data from the process error output
    */
   public abstract InputStream getErrorStream();
 
   /**
    * The thread calling <code>waitFor</code> will block until the subprocess
-   * has terminated.  If the process has already terminated then the method
+   * has terminated. If the process has already terminated then the method
    * immediately returns with the exit value of the subprocess.
-   * 
-   * @returns the exit value of the subprocess.  A return of <code>0</code> 
-   * denotes normal process termination by convention.
    *
-   * @throws InterruptedException is thrown if another thread interrupts 
-   * the waiting thread.  The waiting thread stops waiting.
+   * @return the subprocess exit value; 0 conventionally denotes success
+   * @throws InterruptedException if another thread interrups the blocked one
    */
-  public abstract int waitFor()
-    throws InterruptedException;
+  public abstract int waitFor() throws InterruptedException;
 
   /**
    * When a process terminates there is associated with that termination
-   * an exit value for the process to indicate why it terminated.  A return
+   * an exit value for the process to indicate why it terminated. A return
    * of <code>0</code> denotes normal process termination by convention.
    *
-   * @returns the exit value of the subprocess.
-   * @throws IllegalThreadStateException is thrown if the subprocess 
-   * represented by the subclass of this class has not yet terminated.
+   * @return the exit value of the subprocess
+   * @throws IllegalThreadStateException if the subprocess has not terminated
    */
   public abstract int exitValue();
 
@@ -113,5 +125,4 @@ public abstract class Process
    * Kills the subprocess and all of its children forcibly.
    */
   public abstract void destroy();
-
-}
+} // class Process
diff --git a/libjava/java/lang/Runnable.java b/libjava/java/lang/Runnable.java
index 3632a81..fd817b0 100644
--- a/libjava/java/lang/Runnable.java
+++ b/libjava/java/lang/Runnable.java
@@ -1,5 +1,5 @@
-/* java.lang.Runnable
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* Runnable -- interface for a method tied to an Object; often for Threads
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,12 +38,6 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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:  Complete.
- */
-
 /**
  * Runnable is an interface you implement to indicate that your class can be
  * executed as the main part of a Thread, among other places.  When you want
@@ -52,14 +46,17 @@ package java.lang;
  *
  * @author Paul Fisher
  * @author Tom Tromey <tromey@cygnus.com>
+ * @see Thread
+ * @since 1.0
+ * @status updated to 1.4
  */
-
 public interface Runnable
 {
   /**
    * This method will be called by whoever wishes to run your class
-   * implementing Runnable.
-   * @since JDK1.0
+   * implementing Runnable. Note that there are no restrictions on what
+   * you are allowed to do in the run method, except that you cannot
+   * throw a checked exception.
    */
   void run();
 }
diff --git a/libjava/java/lang/RuntimePermission.java b/libjava/java/lang/RuntimePermission.java
index 81bc44c..0b5b5f8 100644
--- a/libjava/java/lang/RuntimePermission.java
+++ b/libjava/java/lang/RuntimePermission.java
@@ -1,5 +1,5 @@
-/* RuntimePermission.java
-   Copyright (C) 1998, 2000 Free Software Foundation, Inc.
+/* RuntimePermission.java -- permission for a secure runtime action
+   Copyright (C) 1998, 2000, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,14 +38,14 @@ exception statement from your version. */
 
 package java.lang;
 
-import java.security.*;
+import java.security.BasicPermission;
 
 /**
  * A <code>RuntimePermission</code> contains a permission name, but no
  * actions list.  This means you either have the permission or you don't.
  *
  * Permission names have the follow the hierarchial property naming
- * convention.  In addition, an asterisk may appear at the end of a 
+ * convention.  In addition, an asterisk may appear at the end of a
  * name if following a period or by itself.
  *
  * <table border=1>
@@ -53,112 +53,156 @@ import java.security.*;
  * <tr><td>"accessClassInPackage.*","*"</td>
  * <td>"**", "*x", "*.a"</td></tr>
  * </table>
- * <br> 
- * 
- * The following table provides a list of all the possible RuntimePermission
- * permission names with a description of what that permission allows.
  * <br>
+ *
+ * The following table provides a list of all the possible RuntimePermission
+ * permission names with a description of what that permission allows.<br>
  * <table border=1>
- * <tr><th>Permission Name</th><th>Permission Allows</th></tr>
+ * <tr><th>Permission Name</th><th>Permission Allows</th><th>Risks</th</tr>
  * <tr>
  *   <td><code>createClassLoader</code></td>
- *   <td>creation of a class loader</td></tr>
+ *   <td>creation of a class loader</td>
+ *   <td>a class loader can load rogue classes which bypass all security
+ *       permissions</td></tr>
  * <tr>
  *   <td><code>getClassLoader</code></td>
- *   <td>retrieval of the class loader for the calling class</td></tr>
+ *   <td>retrieval of the class loader for the calling class</td>
+ *   <td>rogue code could load classes not otherwise available</td></tr>
  * <tr>
  *   <td><code>setContextClassLoader</code></td>
- *   <td>allows the setting of the context class loader used by a 
- *       thread including system threads</td></tr>
+ *   <td>allows the setting of the context class loader used by a thread</td>
+ *   <td>rogue code could change the context class loader needed by system
+ *       threads</td></tr>
  * <tr>
  *   <td><code>setSecurityManager</code></td>
- *   <td>allows the application to replace the security manager with
- *       another, possibly less restrictive one.</td></tr>
+ *   <td>allows the application to replace the security manager</td>
+ *   <td>the new manager may be less restrictive, so that rogue code can
+ *       bypass existing security checks</td></tr>
  * <tr>
  *   <td><code>createSecurityManager</code></td>
- *   <td>allows the application to create a new security manager</td></tr>
+ *   <td>allows the application to create a new security manager</td>
+ *   <td>rogue code can use the new security manager to discover information
+ *       about the execution stack</td></tr>
  * <tr>
  *   <td><code>exitVM</code></td>
- *   <td>allows the application to halt the virtual machine</td></tr>
+ *   <td>allows the application to halt the virtual machine</td>
+ *   <td>rogue code can mount a denial-of-service attack by killing the
+ *       virtual machine</td></tr>
+ * <tr>
+ *   <td><code>shutdownHooks</code></td>
+ *   <td>allows registration and modification of shutdown hooks</td>
+ *   <td>rogue code can add a hook that interferes with clean
+ *       virtual machine shutdown</td></tr>
  * <tr>
  *   <td><code>setFactory</code></td>
- *   <td>allows the application to set the socket factory for socket, 
- *       server socket, stream handler, or RMI socket factory.</td></tr>
+ *   <td>allows the application to set the socket factory for socket,
+ *       server socket, stream handler, or RMI socket factory.</td>
+ *   <td>rogue code can create a rogue network object which mangles or
+ *       intercepts data</td></tr>
  * <tr>
  *   <td><code>setIO</code></td>
- *   <td>allows the application to set System.out, System.in, and 
- *       System.err</td></tr>
+ *   <td>allows the application to set System.out, System.in, and
+ *       System.err</td>
+ *   <td>rogue code could sniff user input and intercept or mangle
+ *       output</td></tr>
  * <tr>
  *   <td><code>modifyThread</code></td>
  *   <td>allows the application to modify any thread in the virtual machine
  *       using any of the methods <code>stop</code>, <code>resume</code>,
- *       <code>suspend</code>, <code>setPriority</code>, and 
- *       <code>setName</code> of classs <code>Thread</code></td></tr>
+ *       <code>suspend</code>, <code>setPriority</code>, and
+ *       <code>setName</code> of classs <code>Thread</code></td>
+ *   <td>rogue code could adversely modify system or user threads</td></tr>
  * <tr>
  *   <td><code>stopThread</code></td>
  *   <td>allows the application to <code>stop</code> any thread it has
- *       access to in the system</td></tr>
+ *       access to in the system</td>
+ *   <td>rogue code can stop arbitrary threads</td></tr>
  * <tr>
  *   <td><code>modifyThreadGroup</td>
  *   <td>allows the application to modify thread groups using any of the
- *       methods <code>destroy</code>, <code>resume</code>, 
- *       <code>setDaemon</code>, <code>setMaxPriority</code>, 
+ *       methods <code>destroy</code>, <code>resume</code>,
+ *       <code>setDaemon</code>, <code>setMaxPriority</code>,
  *       <code>stop</code>, and <code>suspend</code> of the class
- *       <code>ThreadGroup</code></td></tr>
+ *       <code>ThreadGroup</code></td>
+ *   <td>rogue code can mount a denial-of-service attack by changing run
+ *       priorities</td></tr>
  * <tr>
  *   <td><code>getProtectionDomain</code></td>
- *   <td></td></tr>
+ *   <td>retrieve a class's ProtectionDomain</td>
+ *   <td>rogue code can gain information about the security policy, to
+ *       prepare a better attack</td></tr>
  * <tr>
  *   <td><code>readFileDescriptor</code></td>
- *   <td></td></tr>
+ *   <td>read a file descriptor</td>
+ *   <td>rogue code can read sensitive information</td></tr>
  * <tr>
- *   <td><code>writeFileDescriptor</code</td>
- *   <td></td></tr>
+ *   <td><code>writeFileDescriptor</code></td>
+ *   <td>write a file descriptor</td>
+ *   <td>rogue code can write files, including viruses, and can modify the
+ *       virtual machine binary; if not just fill up the disk</td></tr>
  * <tr>
- *   <td><code>loadLibrary.{library name}</code></td>
- *   <td></td></tr>
+ *   <td><code>loadLibrary.<code><em>library name</em></td>
+ *   <td>dynamic linking of the named library</td>
+ *   <td>native code can bypass many security checks of pure Java</td></tr>
  * <tr>
- *   <td><code>accessClassInPackage.{package name}</code></td>
- *   <td></td></tr>
+ *   <td><code>accessClassInPackage.</code><em>package name</em></td>
+ *   <td>access to a package via a ClassLoader</td>
+ *   <td>rogue code can access classes not normally available</td></tr>
  * <tr>
- *   <td><code>defineClassInPackage.{package name}</code></td>
- *   <td></td></tr>
+ *   <td><code>defineClassInPackage.</code><em>package name</em></td>
+ *   <td>define a class inside a given package</td>
+ *   <td>rogue code can install rogue classes, including in trusted packages
+ *       like java.security or java.lang</td></tr>
  * <tr>
  *   <td><code>accessDeclaredMembers</code></td>
- *   <td></td></tr>
+ *   <td>access declared class members via reflection</td>
+ *   <td>rogue code can discover information, invoke methods, or modify fields
+ *       that are not otherwise available</td></tr>
  * <tr>
  *   <td><code>queuePrintJob</code></td>
- *   <td></td></tr>
+ *   <td>initiate a print job</td>
+ *   <td>rogue code could make a hard copy of sensitive information, or
+ *       simply waste paper</td></tr>
  * </table>
- * 
- * @since JDK 1.2
- * 
+ *
  * @author Brian Jones
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see BasicPermission
+ * @see Permission
+ * @see SecurityManager
+ * @since 1.2
+ * @status updated to 1.4
  */
-public final class RuntimePermission extends java.security.BasicPermission
+public final class RuntimePermission extends BasicPermission
 {
   /**
-   * 
+   * Compatible with JDK 1.2+.
+   */
+  private static final long serialVersionUID = 7399184964622342223L;
+
+  /**
+   * Create a new permission with the specified name.
+   *
    * @param permissionName the name of the granted permission
-   * 
-   * @throws IllegalArgumentException thrown if the name contains an invalid 
-   * wildcard character
+   * @throws NullPointerException if name is null
+   * @throws IllegalArgumentException thrown if name is empty or invalid
    */
   public RuntimePermission(String permissionName)
     {
-      this(permissionName, null);
+      super(permissionName);
     }
 
   /**
+   * Create a new permission with the specified name. The actions argument
+   * is ignored, as runtime permissions have no actions.
    *
    * @param permissionName the name of the granted permission
-   * @param actions this should always be null
-   * 
-   * @throws IllegalArgumentException throw if the name contains an invalid
-   * wildcard character
+   * @param actions ignored
+   * @throws NullPointerException if name is null
+   * @throws IllegalArgumentException thrown if name is empty or invalid
    */
   public RuntimePermission(String permissionName, String actions)
-    {
-      super(permissionName, actions);
-    }
+  {
+    super(permissionName);
+  }
 }
diff --git a/libjava/java/lang/SecurityException.java b/libjava/java/lang/SecurityException.java
index b2bb1aa..5fbdb4a 100644
--- a/libjava/java/lang/SecurityException.java
+++ b/libjava/java/lang/SecurityException.java
@@ -1,6 +1,5 @@
-/* SecurityException.java -- exception thrown to indicate a security 
-   violation.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* SecurityException.java -- thrown to indicate a security violation
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +7,7 @@ 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
@@ -39,41 +38,37 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * The security manager will throw this exception to indicate a security
- * violation.
+ * violation.  This can occur any time an operation is attempted which is
+ * deemed unsafe by the current security policies.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @see SecurityManager
+ * @status updated to 1.4
  */
 public class SecurityException extends RuntimeException
 {
-  static final long serialVersionUID = 6878364983674394167L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 6878364983674394167L;
 
   /**
    * Create an exception without a message.
    */
   public SecurityException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public SecurityException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/Short.java b/libjava/java/lang/Short.java
index cca710c..54e36a5 100644
--- a/libjava/java/lang/Short.java
+++ b/libjava/java/lang/Short.java
@@ -1,5 +1,5 @@
-/* java.lang.Short
-   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
+/* Short.java -- object wrapper for short
+   Copyright (C) 1998, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -47,35 +47,44 @@ package java.lang;
  *
  * @author Paul Fisher
  * @author John Keiser
- * @since JDK 1.0
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.1
+ * @status updated to 1.4
  */
 public final class Short extends Number implements Comparable
 {
-  static final long serialVersionUID = 7515723908773894738L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = 7515723908773894738L;
 
   /**
-   * The minimum value a <code>short</code> can represent is -32768.
+   * The minimum value a <code>short</code> can represent is -32768 (or
+   * -2<sup>15</sup).
    */
   public static final short MIN_VALUE = -32768;
 
   /**
-   * The minimum value a <code>short</code> can represent is 32767.
+   * The minimum value a <code>short</code> can represent is 32767 (or
+   * 2<sup>15</sup).
    */
-  public static final short MAX_VALUE =  32767;
+  public static final short MAX_VALUE = 32767;
 
   /**
-   * The primitive type <code>short</code> is represented by this 
+   * The primitive type <code>short</code> is represented by this
    * <code>Class</code> object.
    */
   public static final Class TYPE = VMClassLoader.getPrimitiveClass('S');
 
   /**
    * The immutable value of this Short.
+   *
+   * @serial the wrapped short
    */
   private final short value;
 
   /**
-   * Create a <code>Short</code> object representing the value of the 
+   * Create a <code>Short</code> object representing the value of the
    * <code>short</code> argument.
    *
    * @param value the value to use
@@ -86,229 +95,255 @@ public final class Short extends Number implements Comparable
   }
 
   /**
-   * Create a <code>Short</code> object representing the value of the 
+   * Create a <code>Short</code> object representing the value of the
    * argument after conversion to a <code>short</code>.
    *
-   * @param s the string to convert.
+   * @param s the string to convert
+   * @throws NumberFormatException if the String cannot be parsed
    */
-  public Short(String s) throws NumberFormatException
+  public Short(String s)
   {
     value = parseShort(s, 10);
   }
 
   /**
-   * Return a hashcode representing this Object.
-   *
-   * <code>Short</code>'s hash code is calculated by simply returning its
-   * value.
+   * Converts the <code>short</code> to a <code>String</code> and assumes
+   * a radix of 10.
    *
-   * @return this Object's hash code.
+   * @param s the <code>short</code> to convert to <code>String</code>
+   * @return the <code>String</code> representation of the argument
    */
-  public int hashCode()
+  public static String toString(short s)
   {
-    return value;
+    return String.valueOf(s);
   }
 
   /**
-   * If the <code>Object</code> is not <code>null</code>, is an
-   * <code>instanceof</code> <code>Short</code>, and represents
-   * the same primitive <code>short</code> value return 
-   * <code>true</code>.  Otherwise <code>false</code> is returned.
+   * Converts the specified <code>String</code> into a <code>short</code>.
+   * This function assumes a radix of 10.
+   *
+   * @param s the <code>String</code> to convert
+   * @return the <code>short</code> value of <code>s</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
    */
-  public boolean equals(Object obj)
-  {
-    return obj instanceof Short && ((Short)obj).value == value;
-  }
-
-  /**
-   * Converts the <code>short</code> to a <code>String</code> and assumes
-   * a radix of 10.
-   * @param i the <code>short</code> to convert to <code>String</code>
-   * @return the <code>String</code> representation of the argument.
-   */    
-  public static String toString(short i)
+  public static short parseShort(String s)
   {
-    return Integer.toString((int) i);
-  }
-
-  /**
-   * Converts the <code>Short</code> value to a <code>String</code> and
-   * assumes a radix of 10.
-   * @return the <code>String</code> representation of this <code>Short</code>.
-   */    
-  public String toString()
-  {
-    return Integer.toString ((int) value);
+    return parseShort(s, 10);
   }
 
   /**
-   * Creates a new <code>Short</code> object using the <code>String</code>,
-   * assuming a radix of 10.
-   * @param s the <code>String</code> to convert.
-   * @return the new <code>Short</code>.
-   * @see #Short(java.lang.String)
-   * @see #parseShort(java.lang.String)
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.
+   * Converts the specified <code>String</code> into a <code>short</code>
+   * using the specified radix (base). The string must not be <code>null</code>
+   * or empty. It may begin with an optional '-', which will negate the answer,
+   * provided that there are also valid digits. Each digit is parsed as if by
+   * <code>Character.digit(d, radix)</code>, and must be in the range
+   * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
+   * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
+   * Unlike Double.parseDouble, you may not have a leading '+'.
+   *
+   * @param s the <code>String</code> to convert
+   * @param radix the radix (base) to use in the conversion
+   * @return the <code>String</code> argument converted to </code>short</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
    */
-  public static Short valueOf(String s) throws NumberFormatException
+  public static short parseShort(String s, int radix)
   {
-    return new Short(parseShort(s));
+    int i = Integer.parseInt(s, radix, false);
+    if ((short) i != i)
+      throw new NumberFormatException();
+    return (short) i;
   }
 
   /**
    * Creates a new <code>Short</code> object using the <code>String</code>
    * and specified radix (base).
-   * @param s the <code>String</code> to convert.
-   * @param radix the radix (base) to convert with.
-   * @return the new <code>Short</code>.
-   * @see #parseShort(java.lang.String,int)
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.
-   */
-  public static Short valueOf(String s, int radix)
-    throws NumberFormatException
-  {
-    return new Short(parseShort(s, radix));
-  }
-
-  /**
-   * Converts the specified <code>String</code> into a <code>short</code>.
-   * This function assumes a radix of 10.
    *
    * @param s the <code>String</code> to convert
-   * @return the <code>short</code> value of the <code>String</code>
-   *         argument.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.
+   * @param radix the radix (base) to convert with
+   * @return the new <code>Short</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
+   * @see #parseShort(String, int)
    */
-  public static short parseShort(String s) throws NumberFormatException
+  public static Short valueOf(String s, int radix)
   {
-    return parseShort(s, 10);
+    return new Short(parseShort(s, radix));
   }
 
   /**
-   * Converts the specified <code>String</code> into a <code>short</code>
-   * using the specified radix (base).
+   * Creates a new <code>Short</code> object using the <code>String</code>,
+   * assuming a radix of 10.
    *
    * @param s the <code>String</code> to convert
-   * @param radix the radix (base) to use in the conversion
-   * @return the <code>String</code> argument converted to </code>short</code>.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.
+   * @return the new <code>Short</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
+   * @see #Short(String)
+   * @see #parseShort(String)
    */
-  public static short parseShort(String s, int radix) 
-    throws NumberFormatException
+  public static Short valueOf(String s)
   {
-    int i = Integer.parseInt(s, radix);
-    if (i < MIN_VALUE || i > MAX_VALUE)
-      throw new NumberFormatException();
-    return (short) i;
+    return new Short(parseShort(s, 10));
   }
 
   /**
    * Convert the specified <code>String</code> into a <code>Short</code>.
-   * The <code>String</code> may represent decimal, hexadecimal, or 
+   * The <code>String</code> may represent decimal, hexadecimal, or
    * octal numbers.
    *
-   * The <code>String</code> argument is interpreted based on the leading
-   * characters.  Depending on what the String begins with, the base will be
-   * interpreted differently:
-   *
-   * <table>
-   * <tr><th>Leading<br>Characters</th><th>Base</th></tr>
-   * <tr><td>#</td><td>16</td></tr>
-   * <tr><td>0x</td><td>16</td></tr>
-   * <tr><td>0X</td><td>16</td></tr>
-   * <tr><td>0</td><td>8</td></tr>
-   * <tr><td>Anything<br>Else</td><td>10</td></tr>
-   * </table>
+   * <p>The extended BNF grammar is as follows:<br>
+   * <pre>
+   * <em>DecodableString</em>:
+   *      ( [ <code>-</code> ] <em>DecimalNumber</em> )
+   *    | ( [ <code>-</code> ] ( <code>0x</code> | <code>0X</code>
+   *              | <code>#</code> ) <em>HexDigit</em> { <em>HexDigit</em> } )
+   *    | ( [ <code>-</code> ] <code>0</code> { <em>OctalDigit</em> } )
+   * <em>DecimalNumber</em>:
+   *        <em>DecimalDigit except '0'</em> { <em>DecimalDigit</em> }
+   * <em>DecimalDigit</em>:
+   *        <em>Character.digit(d, 10) has value 0 to 9</em>
+   * <em>OctalDigit</em>:
+   *        <em>Character.digit(d, 8) has value 0 to 7</em>
+   * <em>DecimalDigit</em>:
+   *        <em>Character.digit(d, 16) has value 0 to 15</em>
+   * </pre>
+   * Finally, the value must be in the range <code>MIN_VALUE</code> to
+   * <code>MAX_VALUE</code>, or an exception is thrown.
    *
-   * @param s the <code>String</code> to interpret.
-   * @return the value of the String as a <code>Short</code>.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.    
+   * @param s the <code>String</code> to interpret
+   * @return the value of the String as a <code>Short</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
+   * @throws NullPointerException if <code>s</code> is null
+   * @see Integer#decode(String)
    */
-  public static Short decode(String s) throws NumberFormatException
+  public static Short decode(String s)
   {
-    int i = (Integer.decode(s)).intValue();
-    if (i < MIN_VALUE || i > MAX_VALUE)
+    int i = Integer.parseInt(s, 10, true);
+    if ((short) i != i)
       throw new NumberFormatException();
     return new Short((short) i);
   }
 
-  /** Return the value of this <code>Short</code> as an <code>short</code>.
-   ** @return the value of this <code>Short</code> as an <code>short</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as a <code>byte</code>.
+   *
+   * @return the byte value
+   */
   public byte byteValue()
   {
     return (byte) value;
   }
 
-  /** Return the value of this <code>Short</code> as an <code>short</code>.
-   ** @return the value of this <code>Short</code> as an <code>short</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code>.
+   *
+   * @return the short value
+   */
   public short shortValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Short</code> as an <code>int</code>.
-   ** @return the value of this <code>Short</code> as an <code>int</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as an <code>int</code>.
+   *
+   * @return the int value
+   */
   public int intValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Short</code> as a <code>long</code>.
-   ** @return the value of this <code>Short</code> as a <code>long</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as a <code>long</code>.
+   *
+   * @return the long value
+   */
   public long longValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Short</code> as a <code>float</code>.
-   ** @return the value of this <code>Short</code> as a <code>float</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as a <code>float</code>.
+   *
+   * @return the float value
+   */
   public float floatValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Short</code> as a <code>double</code>.
-   ** @return the value of this <code>Short</code> as a <code>double</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as a <code>double</code>.
+   *
+   * @return the double value
+   */
   public double doubleValue()
   {
     return value;
   }
 
   /**
-   * Compare two Shorts numerically by comparing their
-   * <code>short</code> values.
-   * @return a positive value if this <code>Short</code> is greater
-   * in value than the argument <code>Short</code>; a negative value
-   * if this <code>Short</code> is smaller in value than the argument
-   * <code>Short</code>; and <code>0</code>, zero, if this
-   * <code>Short</code> is equal in value to the argument
-   * <code>Short</code>.  
+   * Converts the <code>Short</code> value to a <code>String</code> and
+   * assumes a radix of 10.
+   *
+   * @return the <code>String</code> representation of this <code>Short</code>
+   */
+  public String toString()
+  {
+    return String.valueOf(value);
+  }
+
+  /**
+   * Return a hashcode representing this Object. <code>Short</code>'s hash
+   * code is simply its value.
+   *
+   * @return this Object's hash code
+   */
+  public int hashCode()
+  {
+    return value;
+  }
+
+  /**
+   * Returns <code>true</code> if <code>obj</code> is an instance of
+   * <code>Short</code> and represents the same short value.
+   *
+   * @param obj the object to compare
+   * @return whether these Objects are semantically equal
+   */
+  public boolean equals(Object obj)
+  {
+    return obj instanceof Short && value == ((Short) obj).value;
+  }
+
+  /**
+   * Compare two Shorts numerically by comparing their <code>short</code>
+   * values. The result is positive if the first is greater, negative if the
+   * second is greater, and 0 if the two are equal.
    *
+   * @param s the Short to compare
+   * @return the comparison
    * @since 1.2
    */
   public int compareTo(Short s)
   {
     return value - s.value;
   }
-    
+
   /**
-   * Behaves like <code>compareTo(java.lang.Short)</code> unless the Object
-   * is not a <code>Short</code>.  Then it throws a 
-   * <code>ClassCastException</code>.
-   * @exception ClassCastException if the argument is not a
-   * <code>Short</code>.
+   * Behaves like <code>compareTo(Short)</code> unless the Object
+   * is not a <code>Short</code>.
    *
+   * @param o the object to compare
+   * @return the comparison
+   * @throws ClassCastException if the argument is not a <code>Short</code>
+   * @see #compareTo(Short)
+   * @see Comparable
    * @since 1.2
    */
   public int compareTo(Object o)
diff --git a/libjava/java/lang/StackOverflowError.java b/libjava/java/lang/StackOverflowError.java
index 6a95310..8e8ed8d 100644
--- a/libjava/java/lang/StackOverflowError.java
+++ b/libjava/java/lang/StackOverflowError.java
@@ -1,5 +1,5 @@
-/* StackOverflowError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* StackOverflowError.java -- thrown when the stack depth is exceeded
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,39 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
- * A <code>StackOverflowError</code> is thrown when a stack overflow occurs.
- * This can occur because an application recurses too deeply.
+ * A <code>StackOverflowError</code> is thrown when the execution stack
+ * overflow occurs. This often occurs when a method enters infinit recursion.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class StackOverflowError extends VirtualMachineError
 {
-  static final long serialVersionUID = 8609175038441759607L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 8609175038441759607L;
 
   /**
    * Create an error without a message.
    */
   public StackOverflowError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public StackOverflowError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/StringIndexOutOfBoundsException.java b/libjava/java/lang/StringIndexOutOfBoundsException.java
index 6a2c96f..9a935ee 100644
--- a/libjava/java/lang/StringIndexOutOfBoundsException.java
+++ b/libjava/java/lang/StringIndexOutOfBoundsException.java
@@ -1,6 +1,6 @@
-/* StringIndexOutOfBoundsException.java -- exception thrown to indicate 
-   an attempt to access an index which is out of bounds.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* StringIndexOutOfBoundsException.java -- thrown to indicate attempt to
+   exceed string bounds
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,52 +39,47 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * This exception can be thrown to indicate an attempt to access an
- * index which is out of bounds.
- * Any negative integer less than or equal to -1 and positive 
- * integer greater than or equal to the size of the string is an index
+ * This exception can be thrown to indicate an attempt to access an index
+ * which is out of bounds of a String. Any negative integer, and a positive
+ * integer greater than or equal to the size of the string, is an index
  * which would be out of bounds.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class StringIndexOutOfBoundsException extends IndexOutOfBoundsException
 {
-  static final long serialVersionUID = -6762910422159637258L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -6762910422159637258L;
 
   /**
    * Create an exception without a message.
    */
   public StringIndexOutOfBoundsException()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public StringIndexOutOfBoundsException(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 
   /**
    * Create an exception noting the illegal index.
+   *
+   * @param index the invalid index
    */
   public StringIndexOutOfBoundsException(int index)
-    {
-      super("String index out of range: " + index);
-    }
+  {
+    super("String index out of range: " + index);
+  }
 }
diff --git a/libjava/java/lang/ThreadDeath.java b/libjava/java/lang/ThreadDeath.java
index 8110f96..3ba4cf8 100644
--- a/libjava/java/lang/ThreadDeath.java
+++ b/libjava/java/lang/ThreadDeath.java
@@ -1,5 +1,5 @@
-/* java.lang.ThreadDeath - Special exception registering Thread death.
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* ThreadDeath.java - special exception registering Thread death
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,23 +38,31 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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:  Complete to version 1.1
+/**
+ * ThreadDeath is thrown in a thread when someone calls <code>stop()</code>
+ * on that thread. <b>Important:</b> Make sure you rethrow this exception
+ * if you catch it.  If you don't, the thread will not die.
+ *
+ * <p>This is an Error rather than an exception, so that normal code will
+ * not catch it. It is intended for asynchronous cleanup when using the
+ * deprecated Thread.stop() method.
+ *
+ * @author John Keiser
+ * @author Tom Tromey <tromey@cygnus.com>
+ * @see Thread#stop()
+ * @status updated to 1.4
  */
+public class ThreadDeath extends Error
+{
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4417128565033088268L;
 
-/**
- ** ThreadDeath is thrown in a thread when someone calls <CODE>stop()</CODE> on that thread.
- **
- ** <B>Important:</B> Make sure you rethrow this exception if you catch it.  If you don't, the thread will not die.
- **
- ** @author John Keiser
- ** @author Tom Tromey <tromey@cygnus.com>
- ** @version 1.1.0, 5 Feb 1998, August 26 1998
- ** @since JDK1.0
- ** @see java.lang.Thread#stop()
- **/
-
-public class ThreadDeath extends Error {
+  /**
+   * Create an error without a message.
+   */
+  public ThreadDeath()
+  {
+  }
 }
diff --git a/libjava/java/lang/ThreadLocal.java b/libjava/java/lang/ThreadLocal.java
index f671d4e..b5877f5 100644
--- a/libjava/java/lang/ThreadLocal.java
+++ b/libjava/java/lang/ThreadLocal.java
@@ -1,5 +1,5 @@
-/* java.lang.ThreadLocal
-   Copyright (C) 2000 Free Software Foundation, Inc.
+/* ThreadLocal -- a variable with a unique value per thread
+   Copyright (C) 2000, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -46,131 +46,117 @@ import java.util.WeakHashMap;
  * (through the <code>get()</code> and <code>set()</code> methods)
  * only affects the state of the object as seen by the currently
  * executing Thread.
- * <p>
- * The first time a ThreadLocal object is accessed on a particular
- * Thread (and no state is associated with that Thread yet)
- * the state for that Thread is set by executing the method
- * <code>initialValue()</code>.
- * <p>
- * An example how you can use this:
+ *
+ * <p>The first time a ThreadLocal object is accessed on a particular
+ * Thread, the state for that Thread's copy of the local variable is set by
+ * executing the method <code>initialValue()</code>.
+ *
+ * <p>An example how you can use this:
  * <pre>
- * class Connection {
- *     private static ThreadLocal owner = new ThreadLocal() {
- *        public Object initialValue() {
- *            return("nobody");
- *        }
+ * class Connection
+ * {
+ *   private static ThreadLocal owner = new ThreadLocal()
+ *     {
+ *       public Object initialValue()
+ *       {
+ *         return("nobody");
+ *       }
  *     };
  * ...
  * }
- * </pre>
+ * </pre></br>
+ *
  * Now all instances of connection can see who the owner of the currently
  * executing Thread is by calling <code>owner.get()</code>. By default any
  * Thread would be associated with 'nobody'. But the Connection object could
  * offer a method that changes the owner associated with the Thread on
  * which the method was called by calling <code>owner.put("somebody")</code>.
  * (Such an owner changing method should then be guarded by security checks.)
- * <p>
- * When a Thread is garbage collected all references to values of
+ *
+ * <p>When a Thread is garbage collected all references to values of
  * the ThreadLocal objects associated with that Thread are removed.
  *
+ * @author Mark Wielaard <mark@klomp.org>
+ * @author Eric Blake <ebb9@email.byu.edu>
  * @since 1.2
- * @author Mark Wielaard (mark@klomp.org)
+ * @status updated to 1.4
  */
-public class ThreadLocal {
-	
-	/**
-	 * Trivial container to wrap the stored values.
-	 * Needed to see if the value is null or not yet set.
-	 * If it is not yet set we must call intialValue() once.
-	 * Package local so InheritableThreadLocal can see it.
-	 */
-	final static class Value {
-		final Object value;
-		
-		Value(Object value) {
-			this.value = value;
-		}
-		
-		Object getValue() {
-			return value;
-		}
-	}
-	
-	/**
-	 * Maps Threads to Values. Uses a WeakHashMap so if a Thread is garbage
-	 * collected the reference to the Value will disappear. Only the
-	 * <code>set(Thread, Value)</code> and <code>get(Thread)</code> methods
-	 * access it. Since this can happen from multiple Threads simultaniously
-	 * those methods are synchronized.
-	 */
-	private final Map valueMap = new WeakHashMap();
-	
-	/**
-	 * Creates a ThreadLocal object without associating any value to it
-	 * yet.
-	 */
-	public ThreadLocal() {
-	}
-	
-	/**
-	 * Gets the value associated with the ThreadLocal object for the
-	 * currently executing Thread. If there is no value is associated
-	 * with this Thread yet then the valued returned by the
-	 * <code>initialValue()</code> method is assosiated with this Thread
-	 * and returned.
-	 */
-	public Object get() {
-		Thread currentThread = Thread.currentThread();
-		Value v = get(currentThread);
-		if (v == null) {
-			v = new Value(initialValue());
-			set(currentThread, v);
-		}
-		return v.getValue();
-	}
-	
-	/**
-	 * Gets the Value of this ThreadLocal for a particular Thread.
-	 * It is synchronized so the <code>set(Thread, Value)</code> method cannot
-	 * simultaniously modify the </code>valueMap</code> from another thread.
-	 * Package local so InheritableThreadLocal can access it when a new child
-	 * Thread inherits values from its parent Thread.
-	 */
-	synchronized final Value get(Thread thread) {
-		return (Value)valueMap.get(thread);
-	}
-	
-	/**
-	 * Sets the value associated with the ThreadLocal object for the
-	 * currently executing Thread. This overrides any existing value
-	 * associated with the current Thread and does not call the
-	 * <code>initialValue()</code> method, even if this is the first
-	 * time this Thread accesses this ThreadLocal.
-	 */
-	public void set(Object value) {
-		Thread currentThread = Thread.currentThread();
-		Value v = new Value(value);
-		set(currentThread, v);
-	}
+public class ThreadLocal
+{
+  /**
+   * Placeholder to distinguish between uninitialized and null set by the
+   * user. Do not expose this to the public. Package visible for use by
+   * InheritableThreadLocal
+   */
+  static final Object NULL = new Object();
+
+  /**
+   * The stored value. Package visible for use by InheritableThreadLocal. */
+  Object value;
 	
-	/**
-	 * Sets the Value for this ThreadLocal for a particular Thread.
-	 * It is synchronized so the <code>get(Thread)</code> method cannot
-	 * simultaniously read the </code>valueMap</code> from another thread.
-	 * Package local so InheritableThreadLocal can access it when a new child
-	 * Thread inherits values from its parent Thread.
-	 */
-	synchronized final void set(Thread thread, Value value) {
-		valueMap.put(thread, value);
-	}
+  /**
+   * Maps Threads to values. Uses a WeakHashMap so if a Thread is garbage
+   * collected the reference to the Value will disappear. A null value means
+   * uninitialized, while NULL means a user-specified null. Only the
+   * <code>set(Thread, Object)</code> and <code>get(Thread)</code> methods
+   * access it. Package visible for use by InheritableThreadLocal.
+   */
+  final Map valueMap = new WeakHashMap();
 	
-	/**
-	 * Called when <code>get()</code> is called and no state is associated
-	 * with the currently executing Thread yet.
-	 * <p>
-	 * The default implementation returns <code>null</code>.
-	 */
-	protected Object initialValue() {
-		return null;
-	}
+  /**
+   * Creates a ThreadLocal object without associating any value to it yet.
+   */
+  public ThreadLocal()
+  {
+  }
+
+  /**
+   * Called once per thread on the first invocation of get(), if set() was
+   * not already called. The default implementation returns <code>null</code>.
+   * Often, this method is overridden to create the appropriate initial object
+   * for the current thread's view of the ThreadLocal.
+   *
+   * @return the initial value of the variable in this thread
+   */
+  protected Object initialValue()
+  {
+    return null;
+  }
+
+  /**
+   * Gets the value associated with the ThreadLocal object for the currently
+   * executing Thread. If this is the first time the current thread has called
+   * get(), and it has not already called set(), the value is obtained by
+   * <code>initialValue()</code>.
+   *
+   * @return the value of the variable in this thread
+   */
+  public Object get()
+  {
+    Thread currentThread = Thread.currentThread();
+    // Note that we don't have to synchronize, as only this thread will
+    // ever modify the returned value.
+    Object value = valueMap.get(currentThread);
+    if (value == null)
+      {
+        value = initialValue();
+        valueMap.put(currentThread, value == null ? NULL : value);
+      }
+    return value == NULL ? null : value;
+  }
+
+  /**
+   * Sets the value associated with the ThreadLocal object for the currently
+   * executing Thread. This overrides any existing value associated with the
+   * current Thread and prevents <code>initialValue()</code> from being
+   * called if this is the first access to this ThreadLocal in this Thread.
+   *
+   * @param value the value to set this thread's view of the variable to
+   */
+  public void set(Object value)
+  {
+    // Note that we don't have to synchronize, as only this thread will
+    // ever modify the returned value.
+    valueMap.put(Thread.currentThread(), value == null ? NULL : value);
+  }
 }
diff --git a/libjava/java/lang/UnknownError.java b/libjava/java/lang/UnknownError.java
index 2325b40..c200689 100644
--- a/libjava/java/lang/UnknownError.java
+++ b/libjava/java/lang/UnknownError.java
@@ -1,5 +1,6 @@
-/* UnknownError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* UnknownError.java -- thrown when the VM cannot provide more information
+   about a catastrophic error
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +8,7 @@ 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
@@ -38,37 +39,34 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
- * An <code>UnknownError</code> is thrown when a serious but unknown 
+ * An <code>UnknownError</code> is thrown when a serious but unknown
  * problem has occurred in the Java Virtual Machine.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
+ * @status updated to 1.4
  */
 public class UnknownError extends VirtualMachineError
 {
-  static final long serialVersionUID = 2524784860676771849L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 2524784860676771849L;
 
   /**
    * Create an error without a message.
    */
   public UnknownError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public UnknownError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/UnsatisfiedLinkError.java b/libjava/java/lang/UnsatisfiedLinkError.java
index f56bd98..95c0b53 100644
--- a/libjava/java/lang/UnsatisfiedLinkError.java
+++ b/libjava/java/lang/UnsatisfiedLinkError.java
@@ -1,5 +1,5 @@
-/* UnsatisfiedLinkError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* UnsatisfiedLinkError.java -- thrown when a native method cannot be loaded
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,40 +38,37 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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. 
- */
-
 /**
  * A <code>UnsatisfiedLinkError</code> is thrown if an appropriate
  * native language definition of a method declared <code>native</code>
  * cannot be found by the Java Virtual Machine.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @see Runtime
+ * @status updated to 1.4
  */
 public class UnsatisfiedLinkError extends LinkageError
 {
-  static final long serialVersionUID = -4019343241616879428L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4019343241616879428L;
 
   /**
    * Create an error without a message.
    */
   public UnsatisfiedLinkError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public UnsatisfiedLinkError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/UnsupportedClassVersionError.java b/libjava/java/lang/UnsupportedClassVersionError.java
index b90329d..7250949 100644
--- a/libjava/java/lang/UnsupportedClassVersionError.java
+++ b/libjava/java/lang/UnsupportedClassVersionError.java
@@ -1,5 +1,6 @@
-/* UnsupportedClassVersionError.java 
-   Copyright (C) 1998 Free Software Foundation, Inc.
+/* UnsupportedClassVersionError.java -- thrown when a class file version
+   exceeds the capability of the virtual machine
+   Copyright (C) 1998, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +8,7 @@ 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
@@ -43,27 +44,31 @@ package java.lang;
  * Java Virtual Machine determines it does not support the major and minor
  * version numbers in the class file it is attempting to read.
  *
- * @since JDK 1.2
- * 
  * @author Brian Jones
+ * @since 1.2
+ * @status updated to 1.4
  */
 public class UnsupportedClassVersionError extends ClassFormatError
 {
-  static final long serialVersionUID = -7123279212883497373L;
+  /**
+   * Compatible with JDK 1.2+.
+   */
+  private static final long serialVersionUID = -7123279212883497373L;
 
   /**
    * Create an error without a message.
    */
   public UnsupportedClassVersionError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public UnsupportedClassVersionError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/UnsupportedOperationException.java b/libjava/java/lang/UnsupportedOperationException.java
index cda8b2b..6c00bef 100644
--- a/libjava/java/lang/UnsupportedOperationException.java
+++ b/libjava/java/lang/UnsupportedOperationException.java
@@ -1,6 +1,6 @@
-/* UnsupportedOperationException.java -- Exception thrown when an
-   unsupported operation is attempted on an object
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* UnsupportedOperationException.java -- thrown when an operation is not
+   supported
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -8,7 +8,7 @@ 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
@@ -39,37 +39,34 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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 exception is thrown by an object when an operation is
  * requested of it that it does not support.
  *
- * @since JDK 1.2
- *
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @since 1.2
+ * @status updated to 1.4
  */
 public class UnsupportedOperationException extends RuntimeException
 {
-  static final long serialVersionUID = -1242599979055084673L;
+  /**
+   * Compatible with JDK 1.2+.
+   */
+  private static final long serialVersionUID = -1242599979055084673L;
 
   /**
    * Create an exception without a message.
    */
-  public UnsupportedOperationException() 
+  public UnsupportedOperationException()
   {
-    super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
-  public UnsupportedOperationException( String s )
+  public UnsupportedOperationException(String s)
   {
     super(s);
   }
diff --git a/libjava/java/lang/VerifyError.java b/libjava/java/lang/VerifyError.java
index ae291fe..3926530 100644
--- a/libjava/java/lang/VerifyError.java
+++ b/libjava/java/lang/VerifyError.java
@@ -1,5 +1,5 @@
-/* VerifyError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* VerifyError.java -- thrown when a class fails verification
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,39 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
  * A <code>VerifyError</code> is thrown if there is a security problem or
- * internal inconsistency in a class file as deteced by the "verifier."
+ * internal inconsistency in a class file as detected by the "verifier."
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class VerifyError extends LinkageError
 {
-  static final long serialVersionUID = 7001962396098498785L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 7001962396098498785L;
 
   /**
    * Create an error without a message.
    */
   public VerifyError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public VerifyError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/VirtualMachineError.java b/libjava/java/lang/VirtualMachineError.java
index dec999a..b6f0758 100644
--- a/libjava/java/lang/VirtualMachineError.java
+++ b/libjava/java/lang/VirtualMachineError.java
@@ -1,5 +1,5 @@
-/* VirtualMachineError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* VirtualMachineError.java -- thrown when the Virtual Machine has a problem
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,40 +38,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* 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.
- */
-
 /**
- * A <code>VirtualMachineError</code> or its subclasses are thrown to 
+ * A <code>VirtualMachineError</code> or its subclasses are thrown to
  * indicate there is something wrong with the Java Virtual Machine or that
  * it does not have the resources needed for it to continue execution.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public abstract class VirtualMachineError extends Error
 {
-  static final long serialVersionUID = 4161983926571568670L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 4161983926571568670L;
 
   /**
    * Create an error without a message.
    */
   public VirtualMachineError()
-    {
-      super();
-    }
+  {
+  }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public VirtualMachineError(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
 }
diff --git a/libjava/java/lang/reflect/InvocationTargetException.java b/libjava/java/lang/reflect/InvocationTargetException.java
index 3e7a3d3..904cc63 100644
--- a/libjava/java/lang/reflect/InvocationTargetException.java
+++ b/libjava/java/lang/reflect/InvocationTargetException.java
@@ -1,5 +1,5 @@
-/* InvocationTargetException.java - Wrapper exception for reflection
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* InvocationTargetException.java -- Wrapper exception for reflection
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,102 +38,86 @@ exception statement from your version. */
 
 package java.lang.reflect;
 
-import java.io.PrintStream;
-import java.io.PrintWriter;
-
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * Status:  Believed complete and correct.
- */
-
 /**
- * InvocationTargetException is sort of a way to "wrap" whatever exception 
- * comes up when a method or constructor is called via Reflection.
+ * InvocationTargetException is sort of a way to "wrap" whatever exception
+ * comes up when a method or constructor is called via Reflection. As of
+ * JDK 1.4, it was retrofitted to match the exception chaining of all other
+ * exceptions, but <code>getTargetException()</code> still works.
  *
  * @author John Keiser
- * @version 1.1.0, 31 May 1998
  * @author Tom Tromey <tromey@cygnus.com>
- * @date December 12, 1998
- *
+ * @author Eric Blake <ebb9@email.byu.edu>
  * @see Method#invoke(Object,Object[])
  * @see Constructor#newInstance(Object[])
+ * @since 1.1
+ * @status updated to 1.4
  */
-
-public class InvocationTargetException extends Exception 
+public class InvocationTargetException extends Exception
 {
-  static final long serialVersionUID = 4085088731926701167L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = 4085088731926701167L;
+
+  /**
+   * The chained exception. This field is only around for serial compatibility.
+   *
+   * @serial the chained exception
+   */
+  private final Throwable target;
 
-  private Throwable target = null;
-  
-  protected InvocationTargetException() 
-    {
-      super();
-    }
-  
   /**
-   * Create an <code>InvocationTargetException</code> using another 
+   * Construct an exception with null as the cause. The cause is initialized
+   * to null.
+   */
+  protected InvocationTargetException()
+  {
+    this(null, null);
+  }
+
+  /**
+   * Create an <code>InvocationTargetException</code> using another
    * exception.
+   *
    * @param targetException the exception to wrap
    */
-  public InvocationTargetException(Throwable targetException) 
-    {
-      super(targetException.toString());
-      target = targetException;
-    }
-  
-  /** 
-   * Create an <code>InvocationTargetException</code> using another 
+  public InvocationTargetException(Throwable targetException)
+  {
+    this(targetException, null);
+  }
+
+  /**
+   * Create an <code>InvocationTargetException</code> using another
    * exception and an error message.
    *
    * @param targetException the exception to wrap
    * @param err an extra reason for the exception-throwing
    */
-  public InvocationTargetException(Throwable targetException, String err) 
-    {
-      super(err);
-      target = targetException;
-    }
-  
+  public InvocationTargetException(Throwable targetException, String err)
+  {
+    super(err, targetException);
+    target = targetException;
+  }
+
   /**
    * Get the wrapped (targeted) exception.
-   * 
-   * @return the targeted exception.
+   *
+   * @return the targeted exception
+   * @see #getCause()
    */
-  public Throwable getTargetException() 
-    {
-      return target;
-    }
-
-  public void printStackTrace()
-    {
-      if (target == null)
-	super.printStackTrace();
-      else
-      {
-	System.err.print(this.getClass() + ": ");
-	target.printStackTrace();
-      }
-    }
-
-  public void printStackTrace(PrintStream ps)
-    {
-      if (target == null)
-	super.printStackTrace(ps);
-      else
-      {
-	ps.print(this.getClass() + ": ");
-	target.printStackTrace(ps);
-      }
-    }
+  public Throwable getTargetException()
+  {
+    return target;
+  }
 
-  public void printStackTrace(PrintWriter pw)
-    {
-      if (target == null)
-	super.printStackTrace(pw);
-      else
-      {
-	pw.print(this.getClass() + ": ");
-	target.printStackTrace(pw);
-      }
-    }
+  /**
+   * Returns the cause of this exception (which may be null).
+   *
+   * @return the cause
+   * @since 1.4
+   */
+  public Throwable getCause()
+  {
+    return target;
+  }
 }
diff --git a/libjava/java/net/BindException.java b/libjava/java/net/BindException.java
index 5b1e4e7..3d11c4a 100644
--- a/libjava/java/net/BindException.java
+++ b/libjava/java/net/BindException.java
@@ -1,5 +1,5 @@
 /* BindException.java -- An exception occurred while binding to a socket
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -38,49 +38,35 @@ exception statement from your version. */
 package java.net;
 
 /**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
+ * This exception indicates that an error occurred while attempting to bind
+ * socket to a particular port.
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @status updated to 1.4
  */
-
-/**
-  * This exception indicates that an error occurred while attempting to bind
-  * socket to a particular port.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
-  */
 public class BindException extends SocketException
 {
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = -5945005768251722951L;
 
-/*
- * Constructors
- */
-
-/**
-  * Initializes a new instance of <code>BindException</code> without
-  * a descriptive error message.
-  */
-public
-BindException()
-{
-  super();
-}
-
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>BindException</code> with
-  * a descriptive error message, such as the text from strerror(3).
-  *
-  * @param message A message describing the error that occurred.
-  */
-public
-BindException(String message)
-{
-  super(message);
-}
+  /**
+   * Create a new instance without a descriptive error message.
+   */
+  public BindException()
+  {
+  }
 
+  /**
+   * Create a new instance with a descriptive error message, such as the
+   * text from strerror(3).
+   *
+   * @param message a message describing the error that occurred
+   */
+  public BindException(String message)
+  {
+    super(message);
+  }
 } // class BindException
-
diff --git a/libjava/java/net/ConnectException.java b/libjava/java/net/ConnectException.java
index 673561a..e731858 100644
--- a/libjava/java/net/ConnectException.java
+++ b/libjava/java/net/ConnectException.java
@@ -1,5 +1,5 @@
 /* ConnectException.java -- An exception occurred while connecting to a host
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -39,50 +39,37 @@ exception statement from your version. */
 package java.net;
 
 /**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
+ * This exception indicates that an error occurred while attempting to
+ * connect to a remote host.  Often this indicates that the remote host
+ * refused the connection (ie, is not listening on the target socket).
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @since 1.1
+ * @status updated to 1.4
  */
-
-/**
-  * This exception indicates that an error occurred while attempting to
-  * connect to a remote host.  Often this indicates that the remote host
-  * refused the connection (ie, is not listening on the target socket).
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
-  */
 public class ConnectException extends SocketException
 {
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = 3831404271622369215L;
 
-/*
- * Constructors
- */
-
-/**
-  * Initializes a new instance of <code>ConnectException</code> without
-  * a descriptive error message.
-  */
-public
-ConnectException()
-{
-  super();
-}
-
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>ConnectException</code> with
-  * a descriptive error message, such as the text from strerror(3).
-  *
-  * @param message A message describing the error that occurred.
-  */
-public
-ConnectException(String message)
-{
-  super(message);
-}
+  /**
+   * Create a new instance without a descriptive error message.
+   */
+  public ConnectException()
+  {
+  }
 
+  /**
+   * Create a new instance with a descriptive error message, such as the
+   * text from strerror(3).
+   *
+   * @param message a message describing the error that occurred
+   */
+  public ConnectException(String message)
+  {
+    super(message);
+  }
 } // class ConnectException
-
diff --git a/libjava/java/net/MalformedURLException.java b/libjava/java/net/MalformedURLException.java
index a74992b0..9cfae9a 100644
--- a/libjava/java/net/MalformedURLException.java
+++ b/libjava/java/net/MalformedURLException.java
@@ -1,5 +1,5 @@
 /* MalformedURLException.java -- A URL was not in a valid format
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -37,50 +37,37 @@ exception statement from your version. */
 
 package java.net;
 
-/**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
-  * This exception indicates that a URL passed to an object was not in a
-  * valid format.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
-  */
-public class MalformedURLException extends java.io.IOException
-{
-
-/*
- * Constructors
+ * This exception indicates that a URL passed to an object was not in a
+ * valid format.
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @status updated to 1.4
  */
-
-/**
-  * Initializes a new instance of <code>MalformedURLException</code> without
-  * a descriptive error message.
-  */
-public
-MalformedURLException()
+public class MalformedURLException extends IOException
 {
-  super();
-}
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -182787522200415866L;
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>MalformedURLException</code> without
-  * a descriptive error message.
-  *
-  * @param message A message describing the error that occurred.
-  */
-public
-MalformedURLException(String message)
-{
-  super(message);
-}
+  /**
+   * Create a new instance without a descriptive error message.
+   */
+  public MalformedURLException()
+  {
+  }
 
+  /**
+   * Create a new instance with a descriptive error message.
+   *
+   * @param message a message describing the error that occurred
+   */
+  public MalformedURLException(String message)
+  {
+    super(message);
+  }
 } // class MalformedURLException
-
diff --git a/libjava/java/net/NoRouteToHostException.java b/libjava/java/net/NoRouteToHostException.java
index 58ecfba..2f7fb72 100644
--- a/libjava/java/net/NoRouteToHostException.java
+++ b/libjava/java/net/NoRouteToHostException.java
@@ -1,5 +1,5 @@
 /* NoRouteToHostException.java -- Cannot connect to a host
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -39,49 +39,36 @@ exception statement from your version. */
 package java.net;
 
 /**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
-
-/**
   * This exception indicates that there is no TCP/IP route to the requested
   * host.  This is often due to a misconfigured routing table.
   *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Aaron M. Renn <arenn@urbanophile.com>
   * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
+  * @since 1.1
+  * @status updated to 1.4
   */
 public class NoRouteToHostException extends SocketException
 {
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = -1897550894873493790L;
 
-/*
- * Constructors
- */
-
-/**
-  * Initializes an instance of <code>NoRouteToHostException</code>
-  * without a descriptive error message.
-  */
-public
-NoRouteToHostException()
-{
-  super();
-}
-
-/*************************************************************************/
-
-/**
-  * Initializes an instance of <code>NoRouteToHostException</code>
-  * witha descriptive error message, such as the text from strerror(3).
-  *
-  * @param message A message describing the error that occurred.
-  */
-public
-NoRouteToHostException(String message)
-{
-  super(message);
-}
+  /**
+   * Create an instance without a descriptive error message.
+   */
+  public NoRouteToHostException()
+  {
+  }
 
+  /**
+   * Create an instance with a descriptive error message, such as the text
+   * from strerror(3).
+   *
+   * @param message a message describing the error that occurred
+   */
+  public NoRouteToHostException(String message)
+  {
+    super(message);
+  }
 } // class NoRouteToHostException
-
diff --git a/libjava/java/net/ProtocolException.java b/libjava/java/net/ProtocolException.java
index dbdefb7..c50bbcf 100644
--- a/libjava/java/net/ProtocolException.java
+++ b/libjava/java/net/ProtocolException.java
@@ -1,5 +1,5 @@
-/* ProtocolException.java -- A low level protocol error occurred
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* ProtocolException.java -- a low level protocol error occurred
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -37,51 +37,38 @@ exception statement from your version. */
 
 package java.net;
 
-/**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
-  * This exception indicates that some sort of low level protocol
-  * exception occurred.  Look in the descriptive message (if any) for
-  * details on what went wrong
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
-  */
-public class ProtocolException extends java.io.IOException
-{
-
-/*
- * Constructors
+ * This exception indicates that some sort of low level protocol
+ * exception occurred.  Look in the descriptive message (if any) for
+ * details on what went wrong.
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @status updated to 1.4
  */
-
-/**
-  * Initializes a new instance of <code>ProtocolException</code>
-  * without a descriptive error message.
-  */
-public
-ProtocolException()
+public class ProtocolException extends IOException
 {
-  super();
-}
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -6098449442062388080L;
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>ProtocolException</code>
-  * with a descriptive error message.
-  *
-  * @param message A message describing the error that occurred.
-  */
-public
-ProtocolException(String message)
-{
-  super(message);
-}
+  /**
+   * Create a new instance without a descriptive error message.
+   */
+  public ProtocolException()
+  {
+  }
 
+  /**
+   * Create a new instance with a descriptive error message.
+   *
+   * @param message a message describing the error that occurred
+   */
+  public ProtocolException(String message)
+  {
+    super(message);
+  }
 } // class ProtocolException
-
diff --git a/libjava/java/net/SocketException.java b/libjava/java/net/SocketException.java
index 6451b7d..6494cae 100644
--- a/libjava/java/net/SocketException.java
+++ b/libjava/java/net/SocketException.java
@@ -1,5 +1,5 @@
 /* SocketException.java -- An exception occurred while performing a socket op
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -37,49 +37,38 @@ exception statement from your version. */
 
 package java.net;
 
-/* Written using on-line Java Platform 1.2 API Specification.
- * Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
-  * This exception indicates that a generic error occurred related to an
-  * operation on a socket.  Check the descriptive message (if any) for
-  * details on the nature of this error
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  * @author Per Bothner 
-  * @date January 6, 1999.
-  */
-public class SocketException extends java.io.IOException
-{
-
-/*
- * Constructors
+ * This exception indicates that a generic error occurred related to an
+ * operation on a socket.  Check the descriptive message (if any) for
+ * details on the nature of this error
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Per Bothner
+ * @status updated to 1.4
  */
-
-/**
-  * Initializes a new instance of <code>SocketException</code> without
-  * a descriptive error message.
-  */
-public
-SocketException()
+public class SocketException extends IOException
 {
-  super();
-}
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -5935874303556886934L;
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>SocketException</code> without
-  * a descriptive error message.
-  *
-  * @param message A message describing the error that occurred.
-  */
-public
-SocketException(String message)
-{
-  super(message);
-}
+  /**
+   * Create a new instance without a descriptive error message.
+   */
+  public SocketException()
+  {
+  }
 
+  /**
+   * Create a new instance with a descriptive error message.
+   *
+   * @param message a message describing the error that occurred
+   */
+  public SocketException(String message)
+  {
+    super(message);
+  }
 } // class SocketException
-
diff --git a/libjava/java/net/UnknownHostException.java b/libjava/java/net/UnknownHostException.java
index 7a56f26..46b7040 100644
--- a/libjava/java/net/UnknownHostException.java
+++ b/libjava/java/net/UnknownHostException.java
@@ -1,5 +1,5 @@
-/* UnknownHostException.java -- The hostname is not unknown
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* UnknownHostException.java -- The hostname is unknown
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -37,52 +37,40 @@ exception statement from your version. */
 
 package java.net;
 
-/*
- * Written using on-line Java Platform 1.2 API Specification.
- * Status:  Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
-  * This exception indicates that an attempt was made to reference a hostname
-  * or IP address that is not valid.  This could possibly indicate that a
-  * DNS problem has occurred, but most often means that the host was not
-  * correctly specified.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  * @author Per Bothner 
-  * @date January 6, 1999.
-  */
-public class UnknownHostException extends java.io.IOException
-{
-
-/*
- * Constructors
+ * This exception indicates that an attempt was made to reference a hostname
+ * or IP address that is not valid.  This could possibly indicate that a
+ * DNS problem has occurred, but most often means that the host was not
+ * correctly specified.
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Per Bothner
+ * @status updated to 1.4
  */
-
-/**
-  * Initializes a new instance of <code>UnknownHostException</code>
-  * without a descriptive error message.
-  */
-public
-UnknownHostException()
+public class UnknownHostException extends IOException
 {
-  super();
-}
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4639126076052875403L;
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>UnknownHostException</code>
-  * with a descriptive error message, such as the name of the host
-  * that could not be resolved.
-  *
-  * @param message A message describing the error that occurrred.
-  */
-public
-UnknownHostException(String message)
-{
-  super(message);
-}
+  /**
+   * Create a new instance without a descriptive error message.
+   */
+  public UnknownHostException()
+  {
+  }
 
+  /**
+   * Create a new instance with a descriptive error message, such as the
+   * name of the host that could not be resolved.
+   *
+   * @param message a message describing the error that occurred
+   */
+  public UnknownHostException(String message)
+  {
+    super(message);
+  }
 } // class UnknownHostException
-
diff --git a/libjava/java/net/UnknownServiceException.java b/libjava/java/net/UnknownServiceException.java
index 1ccf21d..dfb7a44 100644
--- a/libjava/java/net/UnknownServiceException.java
+++ b/libjava/java/net/UnknownServiceException.java
@@ -1,5 +1,5 @@
 /* UnknownServiceException.java -- A service error occurred
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -7,7 +7,7 @@ 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
@@ -37,52 +37,39 @@ exception statement from your version. */
 
 package java.net;
 
-/**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
-  * Contrary to what you might think, this does not indicate that the
-  * TCP/IP service name specified was invalid.  Instead it indicates that
-  * the MIME type returned from a URL could not be determined or that an
-  * attempt was made to write to a read-only URL.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
-  */
-public class UnknownServiceException extends java.io.IOException
-{
-
-/*
- * Constructors
+ * Contrary to what you might think, this does not indicate that the
+ * TCP/IP service name specified was invalid.  Instead it indicates that
+ * the MIME type returned from a URL could not be determined or that an
+ * attempt was made to write to a read-only URL.
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @status updated to 1.4
  */
-
-/**
-  * Initializes a new instance of <code>UnknownServiceException</code>
-  * without a descriptive error message.
-  */
-public
-UnknownServiceException()
+public class UnknownServiceException extends IOException
 {
-  super();
-}
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4169033248853639508L;
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>UnknownServiceException</code>
-  * without a descriptive error message.
-  *
-  * @param message A message describing the error that occurred.
-  */
-public
-UnknownServiceException(String message)
-{
-  super(message);
-}
+  /**
+   * Create a new instance without a descriptive error message.
+   */
+  public UnknownServiceException()
+  {
+  }
 
+  /**
+   * Create a new instance with a descriptive error message.
+   *
+   * @param message a message describing the error that occurred
+   */
+  public UnknownServiceException(String message)
+  {
+    super(message);
+  }
 } // class UnknownServiceException
-