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

1 files changed, 50 insertions, 22 deletions

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);
 }