   return !(lhs < rhs)
 }
 
-/// Types implementing the `Comparable` protocol can be compared using
-/// relational operators `<`, `<=`, `>=`, `>`.
-///
-/// When adopting `Comparable`, only the `<` operator is required to be
-/// implemented.  The standard library provides implementations for `<=`,
-/// `>=`, `>`.
-///
-/// The `<` operator must define a total order.
+/// Instances of conforming types can be compared using relational
+/// operators, which define a `strict total order
+/// <http://en.wikipedia.org/wiki/Total_order#Strict_total_order>`_.
+///
+/// A type conforming to `Comparable` need only supply the `<` and
+/// `==` operators; default implementations of `<=`, `>`, `>=`, and
+/// `!=` are supplied by the standard library::
+///
+///   struct Singular : Comparable {}
+///   func ==(x: Singular, y: Singular) -> Bool { return true }
+///   func <(x: Singular, y: Singular) -> Bool { return false }
+///
+/// **Axioms**, in addition to those of `Equatable`:
+///
+/// - `x == y` implies `x <= y`, `x >= y`, `!(x < y)`, and `!(x > y)`
+/// - `x < y` implies `x <= y` and `y > x`
+/// - `x > y` implies `x >= y` and `y < x`
+/// - `x <= y` implies `y >= x`
+/// - `x >= y` implies `y <= x`
 public protocol Comparable : _Comparable, Equatable {
   func <=(lhs: Self, rhs: Self) -> Bool
   func >=(lhs: Self, rhs: Self) -> Bool
   func >(lhs: Self, rhs: Self) -> Bool
 }
 
+///
 public protocol BitwiseOperationsType {
   func & (_: Self, _: Self) -> Self
   func |(_: Self, _: Self) -> Self

// Equatable
//

/// Types implementing the `Equatable` protocol can be compared for value
/// equality using operators `==` and `!=`.
///
/// When adopting `Equatable`, only the `==` operator is required to be
/// implemented.  The standard library provides an implementation for `!=`.
///
/// The `==` operator must define an equivalence relation.
public protocol Equatable {
  func == (lhs: Self, rhs: Self) -> Bool
}


//
// Comparable
//

/// This protocol is an implementation detail of `Comparable`; do
/// not use it directly.
///
/// Its requirements are inherited by `Comparable` and thus must
/// be satisfied by types conforming to that protocol.
public protocol _Comparable {
  /// A `strict total order
  /// <http://en.wikipedia.org/wiki/Total_order#Strict_total_order>`_
  /// over instances of `Self`
  func <(lhs: Self, rhs: Self) -> Bool
}

