 // ambiguity indexing CountableRange<T> outside a generic context.
 public enum _DisabledRangeIndex_ {}
 
+/// A type that represents a contiguous range of any comparable value.
+///
+/// - Note: not all empty ranges are equal; it depends on their bounds.
+///
+/// - IXMEFAY: need a more formal description of containment and its
+///   relationship to bounds.  We *can* say that any x > lowerBound
+///   and < upperBound is contained, and containment of the bounds
+///   themselves are up to the model.
 public protocol RangeProtocol : Equatable {
+  
+  /// The representation of the range's endpoints and the values
+  /// contained in it.
   associatedtype Bound : Comparable
-  
+
+  /// Creates an instance with the given bounds.
+  ///
+  /// - Note: as this initializer does not check its precondition, it
+  ///   should be used as an optimization only, when one is absolutely
+  ///   certain that `lower <= upper`.  In general, the `..<` and `...`
+  ///   operators are to be preferred for forming ranges.
+  ///
+  /// - Precondition: `lower <= upper`
   init(uncheckedBounds: (lower: Bound, upper: Bound))
+
+  /// Returns `true` if the range contains the `value`.
+  ///
+  /// - IXMEFAY: need a caveat that this protocol doesn't fully define
+  ///   containment and its relationship to bounds.  
   func contains(value: Bound) -> Bool
+  
+  /// Returns `true` iff `self` and `other` contain a value in common.
   func overlaps(other: Self) -> Bool
+
+  /// Returns `true` iff `self.contains(x)` is `false` for all values of `x`.
   var isEmpty: Bool { get }
   
-  // Note: it is crucial to enforce the invariant that lowerBound <=
-  // upperBound, or when Range has a Stridable Bound, and is thus a
-  // collection, it may be empty with startIndex != endIndex.  Thus,
-  // make sure lowerBound and upperBound are not settable in concrete models.
+  // Note: When the range is also a collection, it is crucial to
+  // enforce the invariant that lowerBound <= upperBound, or it may be
+  // empty with startIndex != endIndex.
+
+  /// The range's lower bound.
+  ///
+  /// - IXMEFAY: vacuous comment
   var lowerBound: Bound { get }
+  
+  /// The range's upper bound.
+  ///
+  /// - IXMEFAY: vacuous comment
   var upperBound: Bound { get }
   
   /// Returns `self` clamped to `limits`.

  }
}

public struct CountableRange<
  // WORKAROUND rdar://25214598 - should be just Bound : Strideable
  Bound : Comparable where Bound : _Strideable, Bound.Stride : Integer

}

extension RangeProtocol {
  /// Creates a copy of `other`.
  @inline(__always)
  public init(_ other: Self) {
    self = other
  }
  
  /// Returns `true` iff `self` and `other` contain a value in common.
  @inline(__always)
  public func overlaps<
    Other: RangeProtocol where Other.Bound == Bound
