Fleshed out scala.math.Ordered documentation.

Contributed by josh marcus.

git-svn-id: http://lampsvn.epfl.ch/svn-repos/scala/scala/trunk@25310 5e8d7ff9-d8ef-0310-90f0-a4852d11357a

Author: extempore

src/library/scala/math/Ordered.scala

@@ -8,42 +8,89 @@
 
 package scala.math
 
-/** A trait for totally ordered data.
+/** A trait for data that have a single, natural ordering.  See 
+ *  [[scala.math.Ordering]] before using this trait for 
+ *  more information about whether to use use [[scala.math.Ordering]] instead.  
+ * 
+ *  Classes that implement this trait can be sorted with 
+ *  [[scala.utils.Sorting]] and can be compared with standard comparison operators
+ *  (e.g. > and <).
  *
- *  Note that since version 2006-07-24 this trait is no longer covariant
- *  in `A`.
+ *  Ordered should be used for data with a single, natural ordering (like
+ *  integers) while Ordering allows for multiple ordering implementations.
+ *  An Ordering instance will be implicitly created if necessary.
+ *
+ *  [[scala.math.Ordering]] is an alternative to this trait that allows multiple orderings to be defined for the same type.
+ * 
+ *  [[scala.math.PartiallyOrdered]] is an alternative to this trait for partially ordered data.
+ *
+ *  For example, to create a simple class that implements Ordered and then sort it with [[scala.utils.Sorting]]:
+ *  {{{
+ *  class OrderedClass(n:Int) extends Ordered[OrderedClass] {
+ *  	def compare(that: OrderedClass) =  this.n - that.n
+ *  }
+ *
+ *  val x = List(new MyClass(1), new MyClass(5), new MyClass(3))
+ *  val result = scala.utils.Sorting.quickSort(x)
+ *  }}}
+ *
+ *  Some additional notes from the initial implementation:
+ * 
+ *  Note that since version 2006-07-24 this trait is no longer covariant in `A`.
  *
  *  It is important that the `equals` method for an instance of `Ordered[A]`
- *  be consistent with the compare method.  However,  due to limitations
- *  inherent in the type erasure semantics, there is no reasonable way to
- *  provide a default implementation of equality for instances of `Ordered[A]`.
- *  Therefore, if you need to be able to use equality on an instance of
- *  `Ordered[A]` you must provide it yourself either when inheriting or
- *  instantiating. 
+ *  	  be consistent with the compare method.  However,  due to limitations
+ *        inherent in the type erasure semantics, there is no reasonable way to
+ *        provide a default implementation of equality for instances of `Ordered[A]`.
+ *        Therefore, if you need to be able to use equality on an instance of
+ *        `Ordered[A]` you must provide it yourself either when inheriting or
+ *        instantiating. 
  *
  *  It is important that the `hashCode` method for an instance of `Ordered[A]`
- *  be consistent with the `compare` method. However, it is not possible to
- *  provide a sensible default implementation. Therefore, if you need to be
- *  able compute the hash of an instance of `Ordered[A]` you must provide it
- *  yourself either when inheriting or instantiating. 
+ *        be consistent with the `compare` method. However, it is not possible to
+ *        provide a sensible default implementation. Therefore, if you need to be
+ *        able compute the hash of an instance of `Ordered[A]` you must provide it
+ *        yourself either when inheriting or instantiating. 
  *
+ *  @see [[scala.math.Ordering]], [[scala.math.PartiallyOrdered]] 
  *  @author  Martin Odersky
  *  @version 1.1, 2006-07-24 
  */
 trait Ordered[A] extends java.lang.Comparable[A] {
 
   /** Result of comparing `this` with operand `that`.
-   *  returns `x` where
-   *  `x &lt; 0`    iff    `this &lt; that`
-   *  `x == 0`     iff    `this == that`
-   *  `x &gt; 0`    iff    `this &gt; that`
+   *
+   * Implement this method to determine how instances of A will be sorted.
+   *
+   * Returns `x` where:
+   *
+   *   - `x < 0` when `this > that`
+   *
+   *   - `x == 0` when `this == that`
+   *
+   *   - `x < 0` when  `this > that`
+   *
    */
   def compare(that: A): Int
 
+  /** Returns true if `this` is less than `that` 
+    */
   def <  (that: A): Boolean = (this compare that) <  0
+
+  /** Returns true if `this` is greater than `that`. 
+    */
   def >  (that: A): Boolean = (this compare that) >  0
+
+  /** Returns true if `this` is less than or equal to `that`.
+    */
   def <= (that: A): Boolean = (this compare that) <= 0
+
+  /** Returns true if `this` is greater than or equal to `that`.
+    */
   def >= (that: A): Boolean = (this compare that) >= 0
+
+  /** Result of comparing `this` with operand `that`.
+    */
   def compareTo(that: A): Int = compare(that)
 }