 // Standard protocols
 //===----------------------------------------------------------------------===//
 
+/// The protocol to which all types implicitly conform
 public typealias Any = protocol<>
+
+/// The protocol to which all classes implicitly conform.
+///
+/// When used as a concrete type, all known `@objc` methods and
+/// properties are available, as implicitly-unwrapped-optional methods
+/// and properties respectively, on each instance of `AnyObject`.  For
+/// example:
+///
+/// .. parsed-literal:
+///
+///   class C {
+///     @objc func getCValue() -> Int { return 42 }
+///   }
+///
+///   // If x has a method @objc getValue()->Int, call it and
+///   // return the result.  Otherwise, return nil.
+///   func getCValue1(x: AnyObject) -> Int? {
+///     if let f: ()->Int = **x.getCValue** {
+///       return f()
+///     }
+///     return nil
+///   }
+///
+///   // A more idiomatic implementation using "optional chaining"
+///   func getCValue2(x: AnyObject) -> Int? {
+///     return **x.getCValue?()**
+///   }
+///
+///   // An implementation that assumes the required method is present
+///   func getCValue3(x: AnyObject) -> **Int** {
+///     return **x.getCValue()** // x.getCValue is implicitly unwrapped.
+///   }
+///
+/// See also: `AnyClass`
 @objc public protocol AnyObject {}
 
+/// The protocol to which all class types implicitly conform.
+///
+/// When used as a concrete type, all known `@objc` `class` methods and
+/// properties are available, as implicitly-unwrapped-optional methods
+/// and properties respectively, on each instance of `AnyClass`. For
+/// example:
+///
+/// .. parsed-literal:
+///
+///   class C {
+///     @objc class var cValue: Int { return 42 }
+///   }
+///
+///   // If x has an @objc cValue: Int, return its value.  
+///   // Otherwise, return nil.
+///   func getCValue(x: AnyClass) -> Int? {
+///     return **x.cValue**
+///   }
+///
+/// See also: `AnyObject`
 public typealias AnyClass = AnyObject.Type
 
 public func === (lhs: AnyObject?, rhs: AnyObject?) -> Bool {

  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.
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

//
// 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
}

