[std::cmp] add missing docs and provide an example

src/libstd/cmp.rs

@@ -10,17 +10,36 @@
 
 /*!
 
-The `Ord` and `Eq` comparison traits
+Defines the `Ord` and `Eq` comparison traits.
 
-This module contains the definition of both `Ord` and `Eq` which define
-the common interfaces for doing comparison. Both are language items
-that the compiler uses to implement the comparison operators. Rust code
-may implement `Ord` to overload the `<`, `<=`, `>`, and `>=` operators,
-and `Eq` to overload the `==` and `!=` operators.
+This module defines both `Ord` and `Eq` traits which are used by the compiler
+to implement comparison operators.
+Rust programs may implement `Ord` to overload the `<`, `<=`, `>`, and `>=` operators,
+and may implement `Eq` to overload the `==` and `!=` operators.
 
-*/
+For example, to define a type with a customized definition for the Eq operators,
+you could do the following:
+
+```rust
+// Our type.
+struct SketchyNum {
+    num : int
+}
+
+// Our implementation of `Eq` to support `==` and `!=`.
+impl Eq for SketchyNum {
+    // Our custom eq allows numbers which are near eachother to be equal! :D
+    fn eq(&self, other: &SketchyNum) -> bool {
+        (self.num - other.num).abs() < 5
+    }
+}
+
+// Now these binary operators will work when applied!
+assert!(SketchyNum {num: 37} == SketchyNum {num: 34});
+assert!(SketchyNum {num: 25} != SketchyNum {num: 57});
+```
 
-#![allow(missing_doc)]
+*/
 
 /**
 * Trait for values that can be compared for equality and inequality.
@@ -35,8 +54,10 @@ and `Eq` to overload the `==` and `!=` operators.
 */
 #[lang="eq"]
 pub trait Eq {
+    /// This method tests for `self` and `other` values to be equal, and is used by `==`.
     fn eq(&self, other: &Self) -> bool;
 
+    /// This method tests for `!=`.
     #[inline]
     fn ne(&self, other: &Self) -> bool { !self.eq(other) }
 }
@@ -55,6 +76,7 @@ pub trait TotalEq: Eq {
     fn assert_receiver_is_total_eq(&self) {}
 }
 
+/// A macro which defines an implementation of TotalEq for a given type.
 macro_rules! totaleq_impl(
     ($t:ty) => {
         impl TotalEq for $t {}
@@ -78,11 +100,29 @@ totaleq_impl!(uint)
 
 totaleq_impl!(char)
 
+/// An ordering is, e.g, a result of a comparison between two values.
 #[deriving(Clone, Eq, Show)]
-pub enum Ordering { Less = -1, Equal = 0, Greater = 1 }
+pub enum Ordering {
+   /// An ordering where a compared value is less [than another].
+   Less = -1,
+   /// An ordering where a compared value is equal [to another].
+   Equal = 0,
+   /// An ordering where a compared value is greater [than another].
+   Greater = 1
+}
 
-/// Trait for types that form a total order
+/// Trait for types that form a total order.
 pub trait TotalOrd: TotalEq + Ord {
+    /// This method returns an ordering between `self` and `other` values.
+    ///
+    /// By convention, `self.cmp(&other)` returns the ordering matching
+    /// the expression `self <operator> other` if true.  For example:
+    ///
+    /// ```
+    /// assert_eq!( 5u.cmp(&10), Less);     // because 5 < 10
+    /// assert_eq!(10u.cmp(&5),  Greater);  // because 10 > 5
+    /// assert_eq!( 5u.cmp(&5),  Equal);    // because 5 == 5
+    /// ```
     fn cmp(&self, other: &Self) -> Ordering;
 }
 
@@ -99,6 +139,7 @@ impl Ord for Ordering {
     fn lt(&self, other: &Ordering) -> bool { (*self as int) < (*other as int) }
 }
 
+/// A macro which defines an implementation of TotalOrd for a given type.
 macro_rules! totalord_impl(
     ($t:ty) => {
         impl TotalOrd for $t {
@@ -128,8 +169,11 @@ totalord_impl!(uint)
 totalord_impl!(char)
 
 /**
-Return `o1` if it is not `Equal`, otherwise `o2`. Simulates the
-lexical ordering on a type `(int, int)`.
+ * Combine orderings, lexically.
+ *
+ * For example for a type `(int, int)`, two comparisons could be done.
+ * If the first ordering is different, the first ordering is all that must be returned.
+ * If the first ordering is equal, then second ordering is returned.
 */
 #[inline]
 pub fn lexical_ordering(o1: Ordering, o2: Ordering) -> Ordering {
@@ -151,11 +195,18 @@ pub fn lexical_ordering(o1: Ordering, o2: Ordering) -> Ordering {
 */
 #[lang="ord"]
 pub trait Ord: Eq {
+    /// This method tests less than (for `self` and `other`) and is used by the `<` operator.
     fn lt(&self, other: &Self) -> bool;
+
+    /// This method tests less than or equal to (`<=`).
     #[inline]
     fn le(&self, other: &Self) -> bool { !other.lt(self) }
+
+    /// This method tests greater than (`>`).
     #[inline]
     fn gt(&self, other: &Self) -> bool {  other.lt(self) }
+
+    /// This method tests greater than or equal to (`>=`).
     #[inline]
     fn ge(&self, other: &Self) -> bool { !self.lt(other) }
 }
@@ -165,14 +216,17 @@ pub trait Ord: Eq {
 /// container types; e.g. it is often desirable to be able to use `&str`
 /// values to look up entries in a container with `~str` keys.
 pub trait Equiv<T> {
+    /// Implement this function to decide equivalent values.
     fn equiv(&self, other: &T) -> bool;
 }
 
+/// Compare and return the minimum of two values.
 #[inline]
 pub fn min<T: TotalOrd>(v1: T, v2: T) -> T {
     if v1 < v2 { v1 } else { v2 }
 }
 
+/// Compare and return the maximum of two values.
 #[inline]
 pub fn max<T: TotalOrd>(v1: T, v2: T) -> T {
     if v1 > v2 { v1 } else { v2 }
@@ -184,11 +238,11 @@ mod test {
 
     #[test]
     fn test_int_totalord() {
-        assert_eq!(5.cmp(&10), Less);
-        assert_eq!(10.cmp(&5), Greater);
-        assert_eq!(5.cmp(&5), Equal);
-        assert_eq!((-5).cmp(&12), Less);
-        assert_eq!(12.cmp(-5), Greater);
+        assert_eq!(5u.cmp(&10), Less);
+        assert_eq!(10u.cmp(&5), Greater);
+        assert_eq!(5u.cmp(&5), Equal);
+        assert_eq!((-5u).cmp(&12), Less);
+        assert_eq!(12u.cmp(-5), Greater);
     }
 
     #[test]
@@ -210,4 +264,24 @@ mod test {
             t(Greater, o, Greater);
          }
     }
+
+    #[test]
+    fn test_user_defined_eq() {
+        // Our type.
+        struct SketchyNum {
+            num : int
+        }
+
+        // Our implementation of `Eq` to support `==` and `!=`.
+        impl Eq for SketchyNum {
+            // Our custom eq allows numbers which are near eachother to be equal! :D
+            fn eq(&self, other: &SketchyNum) -> bool {
+                (self.num - other.num).abs() < 5
+            }
+        }
+
+        // Now these binary operators will work when applied!
+        assert!(SketchyNum {num: 37} == SketchyNum {num: 34});
+        assert!(SketchyNum {num: 25} != SketchyNum {num: 57});
+    }
 }