diff --git a/docs/SIL.rst b/docs/SIL.rst
index 6d227d2..02b5426 100644
--- a/docs/SIL.rst
+++ b/docs/SIL.rst
@@ -1538,15 +1538,16 @@
 
 Class instances and other *heap object references* are pointers at the
 implementation level, but unlike SIL addresses, they are first class values and
-can be ``capture``-d and alias. Swift, however, is memory-safe and statically
+can be ``capture``-d and aliased. Swift, however, is memory-safe and statically
 typed, so aliasing of classes is constrained by the type system as follows:
 
 * A ``Builtin.NativeObject`` may alias any native Swift heap object,
   including a Swift class instance, a box allocated by ``alloc_box``,
   or a thick function's closure context.
   It may not alias natively Objective-C class instances.
-* A ``Builtin.UnknownObject`` may alias any class instance, whether Swift or
-  Objective-C, but may not alias non-class-instance heap objects.
+* A ``Builtin.UnknownObject`` or ``Builtin.BridgeObject`` may alias
+  any class instance, whether Swift or Objective-C, but may not alias
+  non-class-instance heap objects.
 * Two values of the same class type ``$C`` may alias. Two values of related
   class type ``$B`` and ``$D``, where there is a subclass relationship between
   ``$B`` and ``$D``, may alias. Two values of unrelated class types may not
@@ -1560,6 +1561,15 @@
   potentially alias concrete instances of the generic type, such as
   ``$C<Int>``, because ``Int`` is a potential substitution for ``T``.
 
+A violation of the above aliasing rules only results in undefined
+behavior if the aliasing references are dereferenced within Swift code.
+For example,
+``_SwiftNativeNS[Array|Dictionary|String]`` classes alias with
+``NS[Array|Dictionary|String]`` classes even though they are not
+statically related. Since Swift never directly accesses stored
+properties on the Foundation classes, this aliasing does not pose a
+danger.
+
 Typed Access TBAA
 ~~~~~~~~~~~~~~~~~
 
@@ -1571,15 +1581,86 @@
   typed projection operation (e.x. ``ref_element_addr``,
   ``tuple_element_addr``).
 
-It is undefined behavior to perform a typed access to an address or reference if
-the stored object or referent is not an allocated object of the relevant type.
+With limited exceptions, it is undefined behavior to perform a typed access to
+an address or reference addressed memory is not bound to the relevant type.
 
-This allows the optimizer to assume that two addresses cannot alias if there
-does not exist a substitution of archetypes that could cause one of the types to
-be the type of a subobject of the other. Additionally, this applies to the types
-of the values from which the addresses were derived, ignoring "blessed"
-alias-introducing operations such as ``pointer_to_address``, the ``bitcast``
-intrinsic, and the ``inttoptr`` intrinsic.
+This allows the optimizer to assume that two addresses cannot alias if
+there does not exist a substitution of archetypes that could cause one
+of the types to be the type of a subobject of the other. Additionally,
+this applies to the types of the values from which the addresses were
+derived via a typed projection.
+
+Consider the following SIL::
+
+  struct Element {
+    var i: Int
+  }
+  struct S1 {
+    var elt: Element
+  }   
+  struct S2 {
+    var elt: Element
+  }   
+  %adr1 = struct_element_addr %ptr1 : $*S1, #S.elt
+  %adr2 = struct_element_addr %ptr2 : $*S2, #S.elt
+
+The optimizer may assume that ``%adr1`` does not alias with ``%adr2``
+because the values that the addresses are derived from (``%ptr1`` and
+``%ptr2``) have unrelated types. However, in the following example,
+the optimizer cannot assume that ``%adr1`` does not alias with
+``%adr2`` because ``%adr2`` is derived from a cast, and any subsequent
+typed operations on the address will refer to the common ``Element`` type::
+
+  %adr1 = struct_element_addr %ptr1 : $*S1, #S.elt
+  %adr2 = pointer_to_address %ptr2 : $Builtin.RawPointer to $*Element
+
+Exceptions to typed access TBAA rules are only allowed for blessed
+alias-introducing operations. This permits limited type-punning. The only
+current exception is the non-struct ``pointer_to_address`` variant. The
+optimizer must be able to defensively determine that none of the *roots* of an
+address are alias-introducing operations. An address root is the operation that
+produces the address prior to applying any typed projections, indexing, or
+casts. The following are valid address roots:
+
+* Object allocation that generates an address, such as ``alloc_stack``
+  and ``alloc_box``.
+
+* Address-type function arguments. These are crucially *not* considered
+  alias-introducing operations. It is illegal for the SIL optimizer to
+  form a new function argument from an arbitrary address-type
+  value. Doing so would require the optimizer to guarantee that the
+  new argument is both has a non-alias-introducing address root and
+  can be properly represented by the calling convention (address types
+  do not have a fixed representation).
+
+* A strict cast from an untyped pointer, ``pointer_to_address [strict]``. It is
+  illegal for ``pointer_to_address [strict]`` to derive its address from an
+  alias-introducing operation's value. A type punned address may only be
+  produced from an opaque pointer via a non-strict ``pointer_to_address`` at the
+  point of conversion.
+
+Address-to-address casts, via ``unchecked_addr_cast``, transparently
+forward their source's address root, just like typed projections.
+
+Address-type basic block arguments can be conservatively considered
+aliasing-introducing operations; they are uncommon enough not to
+matter and may eventually be prohibited altogether.
+
+Although some pointer producing intrinsics exist, they do not need to be
+considered alias-introducing exceptions to TBAA rules. ``Builtin.inttoptr``
+produces a ``Builtin.RawPointer`` which is not interesting because by definition
+it may alias with everything. Similarly, the LLVM builtins ``Builtin.bitcast``
+and ``Builtin.trunc|sext|zextBitCast`` cannot produce typed pointers. These
+pointer values must be converted to an address via ``pointer_to_address`` before
+typed access can occur. Whether the ``pointer_to_address`` is strict determines
+whether aliasing may occur.
+
+Memory may be rebound to an unrelated type. Addresses to unrelated types may
+alias as long as typed access only occurs while memory is bound to the relevant
+type. Consequently, the optimizer cannot outright assume that addresses accessed
+as unrelated types are nonaliasing. For example, pointer comparison cannot be
+eliminated simply because the two addresses derived from those pointers are
+accessed as unrelated types at different program points.
 
 Value Dependence
 ----------------
diff --git a/docs/Testing.rst b/docs/Testing.rst
index aadea8e..75f3474 100644
--- a/docs/Testing.rst
+++ b/docs/Testing.rst
@@ -273,7 +273,7 @@
   ``armv7``, ``armv7k``, ``arm64``).
 
 * ``%target-os``: the target operating system (``macosx``, ``darwin``,
-  ``linux``, ``freebsd``).
+  ``linux``, ``freebsd``, ``windows-cygnus``, ``windows-gnu``).
 
 * ``%target-object-format``: the platform's object format (``elf``, ``macho``,
   ``coff``).
diff --git a/include/swift/AST/DiagnosticsParse.def b/include/swift/AST/DiagnosticsParse.def
index eaea22d..405f42e 100644
--- a/include/swift/AST/DiagnosticsParse.def
+++ b/include/swift/AST/DiagnosticsParse.def
@@ -1106,8 +1106,6 @@
       "expected ')' to complete '#selector' expression", ())
 
 // Type-of expressions.
-ERROR(expr_typeof_expected_lparen,PointsToFirstBadToken,
-      "expected '(' following 'type'", ())
 ERROR(expr_typeof_expected_label_of,PointsToFirstBadToken,
       "expected argument label 'of:' within 'type(...)'", ())
 ERROR(expr_typeof_expected_expr,PointsToFirstBadToken,
diff --git a/include/swift/AST/DiagnosticsSema.def b/include/swift/AST/DiagnosticsSema.def
index 1ded128..ae0d379 100644
--- a/include/swift/AST/DiagnosticsSema.def
+++ b/include/swift/AST/DiagnosticsSema.def
@@ -72,6 +72,9 @@
 ERROR(could_not_find_type_member,none,
       "type %0 has no member %1", (Type, DeclName))
 
+ERROR(could_not_find_enum_case,none,
+      "enum type %0 has no case %1; did you mean %2", (Type, DeclName, DeclName))
+
 NOTE(did_you_mean_raw_type,none,
      "did you mean to specify a raw type on the enum declaration?", ())
 
@@ -595,8 +598,10 @@
       "protocol %0 can only be used as a generic constraint because it has "
       "Self or associated type requirements", (Identifier))
 
-ERROR(no_decl_in_module,none,
-      "no such decl in module", ())
+ERROR(decl_does_not_exist_in_module,none,
+      "%select{**MODULE**|type|struct|class|enum|protocol|variable|function}0 "
+      "%1 does not exist in module %2",
+      (/*ImportKind*/ unsigned, Identifier, Identifier))
 ERROR(imported_decl_is_wrong_kind,none,
       "%0 was imported as '%1', but is a "
       "%select{**MODULE**|type|struct|class|enum|protocol|variable|function}2",
@@ -2458,8 +2463,6 @@
       "type annotation missing in pattern", ())
 ERROR(refutable_pattern_requires_initializer,none,
       "pattern matching requires an initializer value to match against", ())
-ERROR(invalid_pattern,none,
-      "invalid pattern", ())
 WARNING(var_pattern_didnt_bind_variables,none,
         "'%0' pattern has no effect; sub-pattern didn't bind any variables",
         (StringRef))
diff --git a/lib/ClangImporter/ImportDecl.cpp b/lib/ClangImporter/ImportDecl.cpp
index de55096..bddfaa7 100644
--- a/lib/ClangImporter/ImportDecl.cpp
+++ b/lib/ClangImporter/ImportDecl.cpp
@@ -6087,7 +6087,7 @@
 
     Decl *
     VisitObjCCompatibleAliasDecl(const clang::ObjCCompatibleAliasDecl *decl) {
-      // Import Objective-C’s @compatibility_alias as typealias.
+      // Import Objective-C's @compatibility_alias as typealias.
       EffectiveClangContext effectiveContext(decl->getDeclContext()->getRedeclContext());
       auto dc = Impl.importDeclContextOf(decl, effectiveContext);
       if (!dc) return nullptr;
diff --git a/lib/Driver/Driver.cpp b/lib/Driver/Driver.cpp
index 294b0b1..14a443a 100644
--- a/lib/Driver/Driver.cpp
+++ b/lib/Driver/Driver.cpp
@@ -1316,7 +1316,8 @@
   if (OI.shouldLink() && !AllLinkerInputs.empty()) {
     auto *LinkAction = new LinkJobAction(AllLinkerInputs, OI.LinkAction);
 
-    if (TC.getTriple().getObjectFormat() == llvm::Triple::ELF) {
+    if (TC.getTriple().getObjectFormat() == llvm::Triple::ELF ||
+        TC.getTriple().isOSCygMing()) {
       // On ELF platforms there's no built in autolinking mechanism, so we
       // pull the info we need from the .o files directly and pass them as an
       // argument input file to the linker.
diff --git a/lib/IDE/CodeCompletion.cpp b/lib/IDE/CodeCompletion.cpp
index f91d4f6..18a2dc4 100644
--- a/lib/IDE/CodeCompletion.cpp
+++ b/lib/IDE/CodeCompletion.cpp
@@ -3019,12 +3019,6 @@
                                 optionSetType, conformances);
   }
 
-  bool isOptionSet(Type Ty) {
-    return Ty &&
-           Ty->getNominalOrBoundGenericNominal() &&
-           isOptionSetDecl(Ty->getNominalOrBoundGenericNominal());
-  }
-
   void getTupleExprCompletions(TupleType *ExprType) {
     unsigned Index = 0;
     for (auto TupleElt : ExprType->getElements()) {
diff --git a/lib/Sema/CSDiag.cpp b/lib/Sema/CSDiag.cpp
index 4b95ca6b..ea63bec 100644
--- a/lib/Sema/CSDiag.cpp
+++ b/lib/Sema/CSDiag.cpp
@@ -1948,7 +1948,7 @@
   /// the exact expression kind).
   bool diagnoseGeneralMemberFailure(Constraint *constraint);
   
-  /// Diagnose the lookup of an static member or enum element as instance member.
+  /// Diagnose the lookup of a static member or enum element as instance member.
   void diagnoseTypeMemberOnInstanceLookup(Type baseObjTy,
                                           Expr *baseExpr,
                                           DeclName memberName,
@@ -2448,6 +2448,32 @@
   return;
 }
 
+/// When a user refers a enum case with a wrong member name, we try to find a enum
+/// element whose name differs from the wrong name only in convention; meaning their
+/// lower case counterparts are identical.
+///   - DeclName is valid when such a correct case is found; invalid otherwise.
+static DeclName
+findCorrectEnumCaseName(MetatypeType *MetaTy, LookupResult &Result,
+                        DeclName memberName) {
+  if (!memberName.isSimpleName())
+    return DeclName();
+  if (!MetaTy->getInstanceType()->is<EnumType>())
+    return DeclName();
+  std::vector<DeclName> candidates;
+  for (auto &correction : Result) {
+    DeclName correctName = correction.Decl->getFullName();
+    if (!correctName.isSimpleName())
+      continue;
+    if (!isa<EnumElementDecl>(correction.Decl))
+      continue;
+    if (correctName.getBaseName().str().
+          compare_lower(memberName.getBaseName().str()) == 0)
+      candidates.push_back(correctName);
+  }
+  if (candidates.size() == 1)
+    return candidates.front();
+  return DeclName();
+}
 
 /// Given a result of name lookup that had no viable results, diagnose the
 /// unviable ones.
@@ -2473,10 +2499,17 @@
       diagnose(loc, diag::type_not_subscriptable, baseObjTy)
         .highlight(baseRange);
     } else if (auto MTT = baseObjTy->getAs<MetatypeType>()) {
+      tryTypoCorrection();
+      if (DeclName rightName = findCorrectEnumCaseName(MTT, correctionResults,
+                                                       memberName)) {
+        diagnose(loc, diag::could_not_find_enum_case, MTT->getInstanceType(),
+          memberName, rightName).fixItReplace(nameLoc.getBaseNameLoc(),
+                                              rightName.getBaseName().str());
+        return;
+      }
       diagnose(loc, diag::could_not_find_type_member,
                MTT->getInstanceType(), memberName)
         .highlight(baseRange).highlight(nameLoc.getSourceRange());
-      tryTypoCorrection();
     } else {
       diagnose(loc, diag::could_not_find_value_member,
                baseObjTy, memberName)
diff --git a/lib/Sema/NameBinding.cpp b/lib/Sema/NameBinding.cpp
index 3866786..a69ce26 100644
--- a/lib/Sema/NameBinding.cpp
+++ b/lib/Sema/NameBinding.cpp
@@ -227,7 +227,10 @@
                    /*resolver*/nullptr, &SF);
 
     if (decls.empty()) {
-      diagnose(ID, diag::no_decl_in_module)
+      diagnose(ID, diag::decl_does_not_exist_in_module,
+               static_cast<unsigned>(ID->getImportKind()),
+               declPath.front().first,
+               ID->getModulePath().front().first)
         .highlight(SourceRange(declPath.front().second,
                                declPath.back().second));
       return;
diff --git a/stdlib/private/StdlibUnittest/CMakeLists.txt b/stdlib/private/StdlibUnittest/CMakeLists.txt
index 2eb32e9..e18d39f 100644
--- a/stdlib/private/StdlibUnittest/CMakeLists.txt
+++ b/stdlib/private/StdlibUnittest/CMakeLists.txt
@@ -15,6 +15,7 @@
   # filename.
   StdlibUnittest.swift.gyb
 
+  CheckStrideable.swift.gyb
   InspectValue.cpp
   InspectValue.swift
   InterceptTraps.cpp
diff --git a/stdlib/private/StdlibUnittest/CheckStrideable.swift.gyb b/stdlib/private/StdlibUnittest/CheckStrideable.swift.gyb
new file mode 100644
index 0000000..fbbe590
--- /dev/null
+++ b/stdlib/private/StdlibUnittest/CheckStrideable.swift.gyb
@@ -0,0 +1,32 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2016 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+%{
+from gyb_stdlib_unittest_support import TRACE, stackTrace, trace
+}%
+
+public func checkStrideable<S : Strideable>(
+  instances: [S],
+  distances: [S.Stride],
+  distanceOracle: (Int, Int) -> S.Stride,
+  ${TRACE}
+) {
+  for i in instances.indices {
+    let first = instances[i]
+    for j in instances.indices {
+      let second = instances[j]
+      expectEqual(distanceOracle(i, j), first.distance(to: second))
+      expectEqual(second, first.advanced(by: distanceOracle(i, j)))
+    }
+  }
+}
+
diff --git a/stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb b/stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb
index ba3731d..05d87c1 100644
--- a/stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb
+++ b/stdlib/private/StdlibUnittest/StdlibUnittest.swift.gyb
@@ -150,6 +150,14 @@
   expectEqualTest(expected.2, actual.2, ${trace}, showFrame: false) {$0 == $1}
 }
 
+public func expectEqual<T : Equatable, U : Equatable, V : Equatable, W : Equatable>(
+  _ expected: (T, U, V, W), _ actual: (T, U, V, W), ${TRACE}) {
+  expectEqualTest(expected.0, actual.0, ${trace}, showFrame: false) {$0 == $1}
+  expectEqualTest(expected.1, actual.1, ${trace}, showFrame: false) {$0 == $1}
+  expectEqualTest(expected.2, actual.2, ${trace}, showFrame: false) {$0 == $1}
+  expectEqualTest(expected.3, actual.3, ${trace}, showFrame: false) {$0 == $1}
+}
+
 public func expectationFailure(
   _ reason: String,
   trace message: String,
diff --git a/stdlib/private/StdlibUnittestFoundationExtras/StdlibUnittestFoundationExtras.swift b/stdlib/private/StdlibUnittestFoundationExtras/StdlibUnittestFoundationExtras.swift
index 2cc4380..4337546 100644
--- a/stdlib/private/StdlibUnittestFoundationExtras/StdlibUnittestFoundationExtras.swift
+++ b/stdlib/private/StdlibUnittestFoundationExtras/StdlibUnittestFoundationExtras.swift
@@ -82,6 +82,7 @@
   rangeLength: Int)
 
 extension NSArray {
+  @nonobjc // FIXME: there should be no need in this attribute.
   public func available_getObjects(
     _ objects: AutoreleasingUnsafeMutablePointer<AnyObject?>?, range: NSRange
   ) {
@@ -101,6 +102,7 @@
 )
 
 extension NSDictionary {
+  @nonobjc // FIXME: there should be no need in this attribute.
   public func available_getObjects(
     _ objects: AutoreleasingUnsafeMutablePointer<AnyObject?>?,
     andKeys keys: AutoreleasingUnsafeMutablePointer<AnyObject?>?
diff --git a/stdlib/public/Platform/Platform.swift b/stdlib/public/Platform/Platform.swift
index 7c830d6..a3284be 100644
--- a/stdlib/public/Platform/Platform.swift
+++ b/stdlib/public/Platform/Platform.swift
@@ -124,13 +124,15 @@
 }
 
 public func dprintf(_ fd: Int, _ format: UnsafePointer<Int8>, _ args: CVarArg...) -> Int32 {
-  let va_args = getVaList(args)
-  return vdprintf(Int32(fd), format, va_args)
+  return withVaList(args) { va_args in
+    vdprintf(Int32(fd), format, va_args)
+  }
 }
 
 public func snprintf(ptr: UnsafeMutablePointer<Int8>, _ len: Int, _ format: UnsafePointer<Int8>, _ args: CVarArg...) -> Int32 {
-  let va_args = getVaList(args)
-  return vsnprintf(ptr, len, format, va_args)
+  return withVaList(args) { va_args in
+    return vsnprintf(ptr, len, format, va_args)
+  }
 }
 #endif
 
diff --git a/stdlib/public/SDK/Foundation/ExtraStringAPIs.swift b/stdlib/public/SDK/Foundation/ExtraStringAPIs.swift
index cb79880..607199e 100644
--- a/stdlib/public/SDK/Foundation/ExtraStringAPIs.swift
+++ b/stdlib/public/SDK/Foundation/ExtraStringAPIs.swift
@@ -21,7 +21,7 @@
   }
 
   public func distance(to other: String.UTF16View.Index) -> Int {
-    return other._offset.distance(to: _offset)
+    return _offset.distance(to: other._offset)
   }
 
   public func advanced(by n: Int) -> String.UTF16View.Index {
diff --git a/stdlib/public/SDK/Foundation/Foundation.swift b/stdlib/public/SDK/Foundation/Foundation.swift
index d06016a..bfd1ffe 100644
--- a/stdlib/public/SDK/Foundation/Foundation.swift
+++ b/stdlib/public/SDK/Foundation/Foundation.swift
@@ -501,7 +501,7 @@
 
   @_semantics("convertToObjectiveC")
   public func _bridgeToObjectiveC() -> NSArray {
-    return unsafeBitCast(self._buffer._asCocoaArray() as AnyObject, to: NSArray.self)
+    return unsafeBitCast(self._bridgeToObjectiveCImpl(), to: NSArray.self)
   }
 
   public static func _forceBridgeFromObjectiveC(
diff --git a/stdlib/public/SDK/os/os.swift b/stdlib/public/SDK/os/os.swift
index 7ba4a55..cc396f8 100644
--- a/stdlib/public/SDK/os/os.swift
+++ b/stdlib/public/SDK/os/os.swift
@@ -27,8 +27,9 @@
 		// Since dladdr is in libc, it is safe to unsafeBitCast
                 // the cstring argument type.
 		let str = unsafeBitCast(buf.baseAddress!, to: UnsafePointer<Int8>.self)
-		let valist = getVaList(args)
-		_swift_os_log(dso, log, type, str, valist)
+		withVaList(args) { valist in
+		  _swift_os_log(dso, log, type, str, valist)
+    }
 	}
 }
 
diff --git a/stdlib/public/core/Algorithm.swift b/stdlib/public/core/Algorithm.swift
index 7958b2f..b207029 100644
--- a/stdlib/public/core/Algorithm.swift
+++ b/stdlib/public/core/Algorithm.swift
@@ -10,9 +10,12 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Returns the lesser of `x` and `y`.
+/// Returns the lesser of two comparable values.
 ///
-/// If `x == y`, returns `x`.
+/// - Parameters:
+///   - x: A value to compare.
+///   - y: Another value to compare.
+/// - Returns: The lesser of `x` and `y`. If `x` is equal to `y`, returns `x`.
 public func min<T : Comparable>(_ x: T, _ y: T) -> T {
   // In case `x == y` we pick `x`.
   // This preserves any pre-existing order in case `T` has identity,
@@ -23,7 +26,13 @@
 
 /// Returns the least argument passed.
 ///
-/// If there are multiple equal least arguments, returns the first one.
+/// - Parameters:
+///   - x: A value to compare.
+///   - y: Another value to compare.
+///   - z: A third value to compare.
+///   - rest: Zero or more additional values.
+/// - Returns: The least of all the arguments. If there are multiple equal
+///   least arguments, the result is the first one.
 public func min<T : Comparable>(_ x: T, _ y: T, _ z: T, _ rest: T...) -> T {
   var minValue = min(min(x, y), z)
   // In case `value == minValue`, we pick `minValue`. See min(_:_:).
@@ -33,9 +42,12 @@
   return minValue
 }
 
-/// Returns the greater of `x` and `y`.
+/// Returns the greater of two comparable values.
 ///
-/// If `x == y`, returns `y`.
+/// - Parameters:
+///   - x: A value to compare.
+///   - y: Another value to compare.
+/// - Returns: The greater of `x` and `y`. If `x` is equal to `y`, returns `y`.
 public func max<T : Comparable>(_ x: T, _ y: T) -> T {
   // In case `x == y`, we pick `y`. See min(_:_:).
   return y >= x ? y : x
@@ -43,7 +55,13 @@
 
 /// Returns the greatest argument passed.
 ///
-/// If there are multiple equal greatest arguments, returns the last one.
+/// - Parameters:
+///   - x: A value to compare.
+///   - y: Another value to compare.
+///   - z: A third value to compare.
+///   - rest: Zero or more additional values.
+/// - Returns: The greatest of all the arguments. If there are multiple equal
+///   greatest arguments, the result is the last one.
 public func max<T : Comparable>(_ x: T, _ y: T, _ z: T, _ rest: T...) -> T {
   var maxValue = max(max(x, y), z)
   // In case `value == maxValue`, we pick `value`. See min(_:_:).
@@ -53,18 +71,20 @@
   return maxValue
 }
 
-/// The iterator for `EnumeratedSequence`.  `EnumeratedIterator`
-/// wraps a `Base` iterator and yields successive `Int` values,
-/// starting at zero, along with the elements of the underlying
-/// `Base`:
+/// The iterator for `EnumeratedSequence`.
+///
+/// An instance of `EnumeratedIterator` wraps a base iterator and yields
+/// successive `Int` values, starting at zero, along with the elements of the
+/// underlying base iterator. The following example enumerates the elements of
+/// an array:
 ///
 ///     var iterator = ["foo", "bar"].enumerated().makeIterator()
 ///     iterator.next() // (0, "foo")
 ///     iterator.next() // (1, "bar")
 ///     iterator.next() // nil
 ///
-/// - Note: Idiomatic usage is to call `enumerate` instead of
-///   constructing an `EnumerateIterator` directly.
+/// To create an instance of `EnumeratedIterator`, call
+/// `enumerated().makeIterator()` on a sequence or collection.
 public struct EnumeratedIterator<
   Base : IteratorProtocol
 > : IteratorProtocol, Sequence {
@@ -91,14 +111,22 @@
   }
 }
 
-/// The type of the `enumerated()` property.
+/// An enumeration of the elements of a sequence or collection.
 ///
-/// `EnumeratedSequence` is a sequence of pairs (*n*, *x*), where *n*s
-/// are consecutive `Int`s starting at zero, and *x*s are the elements
-/// of a `Base` `Sequence`:
+/// `EnumeratedSequence` is a sequence of pairs (*n*, *x*), where *n*s are
+/// consecutive `Int` values starting at zero, and *x*s are the elements of a
+/// base sequence.
+///
+/// To create an instance of `EnumeratedSequence`, call `enumerated()` on a
+/// sequence or collection. The following example enumerates the elements of
+/// an array.
 ///
 ///     var s = ["foo", "bar"].enumerated()
-///     Array(s) // [(0, "foo"), (1, "bar")]
+///     for (n, x) in s {
+///         print("\(n): \(x)")
+///     }
+///     // Prints "0: foo"
+///     // Prints "1: bar"
 public struct EnumeratedSequence<Base : Sequence> : Sequence {
   internal var _base: Base
 
@@ -108,8 +136,6 @@
   }
 
   /// Returns an iterator over the elements of this sequence.
-  ///
-  /// - Complexity: O(1).
   public func makeIterator() -> EnumeratedIterator<Base.Iterator> {
     return EnumeratedIterator(_base: _base.makeIterator())
   }
diff --git a/stdlib/public/core/AnyHashable.swift b/stdlib/public/core/AnyHashable.swift
index db4d43d..e81988c 100644
--- a/stdlib/public/core/AnyHashable.swift
+++ b/stdlib/public/core/AnyHashable.swift
@@ -87,14 +87,14 @@
 
 /// A type-erased hashable value.
 ///
-/// Forwards equality comparisons and hashing operations to an
-/// underlying hashable value, hiding its specific type.
+/// The `AnyHashable` type forwards equality comparisons and hashing operations
+/// to an underlying hashable value, hiding its specific underlying type.
 ///
-/// You can store mixed-type keys in `Dictionary` and other
-/// collections that require `Hashable` by wrapping mixed-type keys in
+/// You can store mixed-type keys in dictionaries and other collections that
+/// require `Hashable` conformance by wrapping mixed-type keys in
 /// `AnyHashable` instances:
 ///
-///     let descriptions: [AnyHashable : Any] = [
+///     let descriptions: [AnyHashable: Any] = [
 ///         AnyHashable("😄"): "emoji",
 ///         AnyHashable(42): "an Int",
 ///         AnyHashable(Int8(43)): "an Int8",
@@ -107,17 +107,24 @@
 public struct AnyHashable {
   internal var _box: _AnyHashableBox
 
-  /// Creates an opaque hashable value that wraps `base`.
+  /// Creates a type-erased hashable value that wraps the given instance.
   ///
-  /// Example:
+  /// The following example creates two type-erased hashable values: `x` wraps
+  /// an `Int` with the value 42, while `y` wraps a `UInt8` with the same
+  /// numeric value. Because the underlying types of `x` and `y` are
+  /// different, the two variables do not compare as equal despite having
+  /// equal underlying values.
   ///
   ///     let x = AnyHashable(Int(42))
   ///     let y = AnyHashable(UInt8(42))
   ///
-  ///     print(x == y) // Prints "false" because `Int` and `UInt8`
-  ///                   // are different types.
+  ///     print(x == y)
+  ///     // Prints "false" because `Int` and `UInt8` are different types
   ///
-  ///     print(x == AnyHashable(Int(42))) // Prints "true".
+  ///     print(x == AnyHashable(Int(42)))
+  ///     // Prints "true"
+  ///
+  /// - Parameter base: A hashable value to wrap.
   public init<H : Hashable>(_ base: H) {
     if let customRepresentation =
       (base as? _HasCustomAnyHashableRepresentation)?._toCustomAnyHashable() {
@@ -135,11 +142,16 @@
     self._box = _ConcreteHashableBox(base)
   }
 
-  /// The value wrapped in this `AnyHashable` instance.
+  /// The value wrapped by this instance.
   ///
-  ///     let anyMessage = AnyHashable("Hello")
-  ///     let unwrappedMessage: Any = anyMessage.base
-  ///     print(unwrappedMessage) // prints "hello"
+  /// The `base` property can be cast back to its original type using one of
+  /// the casting operators (`as?`, `as!`, or `as`).
+  ///
+  ///     let anyMessage = AnyHashable("Hello world!")
+  ///     if let unwrappedMessage = anyMessage.base as? String {
+  ///         print(unwrappedMessage)
+  ///     }
+  ///     // Prints "Hello world!"
   public var base: Any {
     return _box._base
   }
@@ -155,6 +167,31 @@
 }
 
 extension AnyHashable : Equatable {
+  /// Returns a Boolean value indicating whether two type-erased hashable
+  /// instances wrap the same type and value.
+  ///
+  /// Two instances of `AnyHashable` compare as equal if and only if the
+  /// underlying types have the same conformance to the `Equatable` protocol
+  /// and the underlying values compare as equal.
+  ///
+  /// The following example creates two type-erased hashable values: `x` wraps
+  /// an `Int` with the value 42, while `y` wraps a `UInt8` with the same
+  /// numeric value. Because the underlying types of `x` and `y` are
+  /// different, the two variables do not compare as equal despite having
+  /// equal underlying values.
+  ///
+  ///     let x = AnyHashable(Int(42))
+  ///     let y = AnyHashable(UInt8(42))
+  ///
+  ///     print(x == y)
+  ///     // Prints "false" because `Int` and `UInt8` are different types
+  ///
+  ///     print(x == AnyHashable(Int(42)))
+  ///     // Prints "true"
+  ///
+  /// - Parameters:
+  ///   - lhs: A type-erased hashable value.
+  ///   - rhs: Another type-erased hashable value.
   public static func == (lhs: AnyHashable, rhs: AnyHashable) -> Bool {
     return lhs._box._isEqual(to: rhs._box)
   }
diff --git a/stdlib/public/core/ArrayBuffer.swift b/stdlib/public/core/ArrayBuffer.swift
index 82b31e8..cd65004 100644
--- a/stdlib/public/core/ArrayBuffer.swift
+++ b/stdlib/public/core/ArrayBuffer.swift
@@ -83,7 +83,7 @@
 
 extension _ArrayBuffer {
   /// Adopt the storage of `source`.
-  public init(_ source: NativeBuffer, shiftedToStartIndex: Int) {
+  public init(_buffer source: NativeBuffer, shiftedToStartIndex: Int) {
     _sanityCheck(shiftedToStartIndex == 0, "shiftedToStartIndex must be 0")
     _storage = _ArrayBridgeStorage(native: source._storage)
   }
@@ -232,7 +232,7 @@
       let boundsCount = bounds.count
       if boundsCount == 0 {
         return _SliceBuffer(
-          _ContiguousArrayBuffer<Element>(),
+          _buffer: _ContiguousArrayBuffer<Element>(),
           shiftedToStartIndex: bounds.lowerBound)
       }
 
@@ -262,7 +262,8 @@
           .assumingMemoryBound(to: AnyObject.self),
         range: _SwiftNSRange(location: bounds.lowerBound, length: boundsCount))
 
-      return _SliceBuffer(result, shiftedToStartIndex: bounds.lowerBound)
+      return _SliceBuffer(
+        _buffer: result, shiftedToStartIndex: bounds.lowerBound)
     }
     set {
       fatalError("not implemented")
diff --git a/stdlib/public/core/ArrayBufferProtocol.swift b/stdlib/public/core/ArrayBufferProtocol.swift
index 5cd21fd..08db658 100644
--- a/stdlib/public/core/ArrayBufferProtocol.swift
+++ b/stdlib/public/core/ArrayBufferProtocol.swift
@@ -24,7 +24,7 @@
   init()
 
   /// Adopt the entire buffer, presenting it at the provided `startIndex`.
-  init(_ buffer: _ContiguousArrayBuffer<Element>, shiftedToStartIndex: Int)
+  init(_buffer: _ContiguousArrayBuffer<Element>, shiftedToStartIndex: Int)
 
   /// Copy the elements in `bounds` from this buffer into uninitialized
   /// memory starting at `target`.  Return a pointer "past the end" of the
diff --git a/stdlib/public/core/Arrays.swift.gyb b/stdlib/public/core/Arrays.swift.gyb
index 9dc60fb..ed975cd 100644
--- a/stdlib/public/core/Arrays.swift.gyb
+++ b/stdlib/public/core/Arrays.swift.gyb
@@ -99,7 +99,7 @@
 ///
 /// You can call any method on the slices that you might have called on the
 /// `absences` array. To learn which half had more absences, use the
-/// `reduce(_:)` method to calculate each sum.
+/// `reduce(_:_:)` method to calculate each sum.
 ///
 ///     let firstHalfSum = firstHalf.reduce(0, +)
 ///     let secondHalfSum = secondHalf.reduce(0, +)
@@ -168,16 +168,15 @@
 /// An ordered, random-access collection.
 ///
 /// Arrays are one of the most commonly used data types in an app. You use
-/// arrays to organize your app's data. Specifically, you use the `Array`
-/// type to hold elements of a single type, the array's `Element` type. An
-/// array's elements can be anything from an integer to a string to a
-/// class.
+/// arrays to organize your app's data. Specifically, you use the `Array` type
+/// to hold elements of a single type, the array's `Element` type. An array's
+/// elements can be anything from an integer to a string to a class.
 ///
-/// Swift makes it easy to create arrays in your code using an array
-/// literal: simply surround a comma-separated list of values with square
-/// brackets. Without any other information, Swift creates an array that
-/// includes the specified values, automatically inferring the array's
-/// `Element` type. For example:
+/// Swift makes it easy to create arrays in your code using an array literal:
+/// simply surround a comma separated list of values with square brackets.
+/// Without any other information, Swift creates an array that includes the
+/// specified values, automatically inferring the array's `Element` type. For
+/// example:
 ///
 ///     // An array of 'Int' elements
 ///     let oddNumbers = [1, 3, 5, 7, 9, 11, 13, 15]
@@ -194,8 +193,8 @@
 ///     // The full type name is also allowed
 ///     var emptyFloats: Array<Float> = Array()
 ///
-/// If you need an array that is preinitialized with a fixed number of
-/// default values, use the `Array(repeating:count:)` initializer.
+/// If you need an array that is preinitialized with a fixed number of default
+/// values, use the `Array(repeating:count:)` initializer.
 ///
 ///     var digitCounts = Array(repeating: 0, count: 10)
 ///     print(digitCounts)
@@ -204,8 +203,8 @@
 /// Accessing Array Values
 /// ======================
 ///
-/// When you need to perform an operation on all of an array's elements, use
-/// a `for`-`in` loop to iterate through the array's contents.
+/// When you need to perform an operation on all of an array's elements, use a
+/// `for`-`in` loop to iterate through the array's contents.
 ///
 ///     for street in streets {
 ///         print("I don't live on \(street).")
@@ -238,10 +237,10 @@
 ///     // Prints "nil, nil"
 ///
 /// You can access individual array elements through a subscript. The first
-/// element of a nonempty array is always at index zero. You can
-/// subscript an array with any integer from zero up to, but not including,
-/// the count of the array. Using a negative number or an index equal to or
-/// greater than `count` triggers a runtime error. For example:
+/// element of a nonempty array is always at index zero. You can subscript an
+/// array with any integer from zero up to, but not including, the count of
+/// the array. Using a negative number or an index equal to or greater than
+/// `count` triggers a runtime error. For example:
 ///
 ///     print(oddNumbers[0], oddNumbers[3], separator: ", ")
 ///     // Prints "1, 7"
@@ -255,52 +254,47 @@
 /// Adding and Removing Elements
 /// ============================
 ///
-/// Suppose you need to store a list of the names of students that are
-/// signed up for a class you're teaching. During the registration period,
-/// you need to add and remove names as students add and drop the class.
+/// Suppose you need to store a list of the names of students that are signed
+/// up for a class you're teaching. During the registration period, you need
+/// to add and remove names as students add and drop the class.
 ///
 ///     var students = ["Ben", "Ivy", "Jordell"]
 ///
-/// More students are signing up. Add single elements to the end of an array
-/// by using the `append(_:)` method. Add multiple elements at once by passing
-/// another array or a sequence of any kind to the `append(contentsOf:)`
-/// method.
+/// To add single elements to the end of an array, use the `append(_:)` method.
+/// Add multiple elements at once by passing another array or a sequence of
+/// any kind to the `append(contentsOf:)` method.
 ///
 ///     students.append("Maxime")
 ///     students.append(contentsOf: ["Shakia", "William"])
+///     // ["Ben", "Ivy", "Jordell", "Maxime", "Shakia", "William"]
 ///
-///     print(students)
-///     // Prints "["Ben", "Ivy", "Jordell", "Maxime", "Shakia", "William"]"
-///
-/// Another last-minute addition! Add new elements into the middle of the
-/// array by using the `insert(_:at:)` method for single elements and
-/// by using `insert(contentsOf:at:)` to insert multiple elements from another
+/// You can add new elements in the middle of an array by using the
+/// `insert(_:at:)` method for single elements and by using
+/// `insert(contentsOf:at:)` to insert multiple elements from another
 /// collection or array literal. The elements at that index and later are
 /// shifted back to make room.
 ///
-///     // Welcome, Liam!
 ///     students.insert("Liam", at: 3)
+///     // ["Ben", "Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]
 ///
-/// A couple of students can't take your class after all. Use the
-/// `removeLast()` and `remove(at:)` methods to remove their names
-/// from the array.
+/// To remove elements from an array, use the `remove(at:)`,
+/// `removeSubrange(_:)`, and `removeLast()` methods.
 ///
 ///     // Ben's family is moving to another state
 ///     students.remove(at: 0)
+///     // ["Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]
 ///
 ///     // William is signing up for a different class
 ///     students.removeLast()
+///     // ["Ivy", "Jordell", "Liam", "Maxime", "Shakia"]
 ///
-///     print(students)
-///     // Prints "["Ivy", "Jordell", "Liam", "Maxime", "Shakia"]"
-///
-/// On the first day, you learn that Maxime really prefers to go by Max.
-/// Replace an existing element with a new value by assigning to the
+/// You can replace an existing element with a new value by assigning to the
 /// subscript.
 ///
 ///     if let i = students.index(of: "Maxime") {
 ///         students[i] = "Max"
 ///     }
+///     // ["Ivy", "Jordell", "Liam", "Max", "Shakia"]
 ///
 /// Growing the Size of an Array
 /// ----------------------------
@@ -308,21 +302,20 @@
 /// Every array reserves a specific amount of memory to hold its contents. When
 /// you add elements to an array and that array begins to exceed its reserved
 /// capacity, the array allocates a larger region of memory and copies its
-/// elements into the new storage. The new storage is a multiple of the
-/// old storage's size. This exponential growth strategy means that appending
-/// an element happens in constant time, averaging the performance of many
-/// append operations. Append operations that trigger reallocation have a
-/// performance cost, but they occur less and less often as the array grows
-/// larger.
+/// elements into the new storage. The new storage is a multiple of the old
+/// storage's size. This exponential growth strategy means that appending an
+/// element happens in constant time, averaging the performance of many append
+/// operations. Append operations that trigger reallocation have a performance
+/// cost, but they occur less and less often as the array grows larger.
 ///
-/// If you know approximately how many elements you will need to store, use
-/// the `reserveCapacity(_:)` method before appending to the array to avoid
-/// intermediate reallocations. Use the `capacity` and `count` properties
-/// to determine how many more elements the array can store without
-/// allocating larger storage.
+/// If you know approximately how many elements you will need to store, use the
+/// `reserveCapacity(_:)` method before appending to the array to avoid
+/// intermediate reallocations. Use the `capacity` and `count` properties to
+/// determine how many more elements the array can store without allocating
+/// larger storage.
 ///
-/// For arrays of most `Element` types, this storage is a contiguous block
-/// of memory. For arrays with an `Element` type that is a class or `@objc`
+/// For arrays of most `Element` types, this storage is a contiguous block of
+/// memory. For arrays with an `Element` type that is a class or `@objc`
 /// protocol type, this storage can be a contiguous block of memory or an
 /// instance of `NSArray`. Because any arbitrary subclass of `NSArray` can
 /// become an `Array`, there are no guarantees about representation or
@@ -331,10 +324,10 @@
 /// Modifying Copies of Arrays
 /// ==========================
 ///
-/// Each array has an independent value that includes the values of all of
-/// its elements. For simple types such as integers and other structures,
-/// this means that when you change a value in one array, the value of that
-/// element does not change in any copies of the array. For example:
+/// Each array has an independent value that includes the values of all of its
+/// elements. For simple types such as integers and other structures, this
+/// means that when you change a value in one array, the value of that element
+/// does not change in any copies of the array. For example:
 ///
 ///     var numbers = [1, 2, 3, 4, 5]
 ///     var numbersCopy = numbers
@@ -344,13 +337,13 @@
 ///     print(numbersCopy)
 ///     // Prints "[1, 2, 3, 4, 5]"
 ///
-/// If the elements in an array are instances of a class, the semantics are
-/// the same, though they might appear different at first. In this case,
-/// the values stored in the array are references to objects that live
-/// outside the array. If you change a reference to an object in one array,
-/// only that array has a reference to the new object. However, if two
-/// arrays contain references to the same object, you can observe changes
-/// to that object's properties from both arrays. For example:
+/// If the elements in an array are instances of a class, the semantics are the
+/// same, though they might appear different at first. In this case, the
+/// values stored in the array are references to objects that live outside the
+/// array. If you change a reference to an object in one array, only that
+/// array has a reference to the new object. However, if two arrays contain
+/// references to the same object, you can observe changes to that object's
+/// properties from both arrays. For example:
 ///
 ///     // An integer type with reference semantics
 ///     class IntegerReference {
@@ -374,21 +367,21 @@
 ///
 /// Arrays, like all variable-size collections in the standard library, use
 /// copy-on-write optimization. Multiple copies of an array share the same
-/// storage until you modify one of the copies. When that happens, the
-/// array being modified replaces its storage with a uniquely owned copy of
-/// itself, which is then modified in place. Optimizations are sometimes
-/// applied that can reduce the amount of copying.
+/// storage until you modify one of the copies. When that happens, the array
+/// being modified replaces its storage with a uniquely owned copy of itself,
+/// which is then modified in place. Optimizations are sometimes applied that
+/// can reduce the amount of copying.
 ///
-/// This means that if an array is sharing storage with other copies, the
-/// first mutating operation on that array incurs the cost of copying the
-/// array. An array that is the sole owner of its storage can perform
-/// mutating operations in place.
+/// This means that if an array is sharing storage with other copies, the first
+/// mutating operation on that array incurs the cost of copying the array. An
+/// array that is the sole owner of its storage can perform mutating
+/// operations in place.
 ///
 /// In the example below, a `numbers` array is created along with two copies
 /// that share the same storage. When the original `numbers` array is
 /// modified, it makes a unique copy of its storage before making the
-/// modification. Further modifications to `numbers` are made in place,
-/// while the two copies continue to share the original storage.
+/// modification. Further modifications to `numbers` are made in place, while
+/// the two copies continue to share the original storage.
 ///
 ///     var numbers = [1, 2, 3, 4, 5]
 ///     var firstCopy = numbers
@@ -412,11 +405,11 @@
 /// Foundation type.
 ///
 /// The following example shows how you can bridge an `Array` instance to
-/// `NSArray` to use the `write(to:atomically:)` method. In this
-/// example, the `colors` array can be bridged to `NSArray` because its
-/// `String` elements bridge to `NSString`. The compiler prevents bridging
-/// the `moreColors` array, on the other hand, because its `Element` type
-/// is `Optional<String>`, which does *not* bridge to a Foundation type.
+/// `NSArray` to use the `write(to:atomically:)` method. In this example, the
+/// `colors` array can be bridged to `NSArray` because its `String` elements
+/// bridge to `NSString`. The compiler prevents bridging the `moreColors`
+/// array, on the other hand, because its `Element` type is
+/// `Optional<String>`, which does *not* bridge to a Foundation type.
 ///
 ///     let colors = ["periwinkle", "rose", "moss"]
 ///     let moreColors: [String?] = ["ochre", "pine"]
@@ -429,17 +422,17 @@
 ///     // error: cannot convert value of type '[String?]' to type 'NSArray'
 ///
 /// Bridging from `Array` to `NSArray` takes O(1) time and O(1) space if the
-/// array's elements are already instances of a class or an `@objc`
-/// protocol; otherwise, it takes O(n) time and space.
+/// array's elements are already instances of a class or an `@objc` protocol;
+/// otherwise, it takes O(n) time and space.
 ///
 /// Bridging from `NSArray` to `Array` first calls the `copy(with:)`
 /// (`- copyWithZone:` in Objective-C) method on the array to get an immutable
 /// copy and then performs additional Swift bookkeeping work that takes O(1)
-/// time. For instances of `NSArray` that are already immutable,
-/// `copy(with:)` usually returns the same array in O(1) time; otherwise,
-/// the copying performance is unspecified. The instances of `NSArray` and
-/// `Array` share storage using the same copy-on-write optimization that is
-/// used when two instances of `Array` share storage.
+/// time. For instances of `NSArray` that are already immutable, `copy(with:)`
+/// usually returns the same array in O(1) time; otherwise, the copying
+/// performance is unspecified. The instances of `NSArray` and `Array` share
+/// storage using the same copy-on-write optimization that is used when two
+/// instances of `Array` share storage.
 ///
 /// - Note: The `ContiguousArray` and `ArraySlice` types are not bridged;
 ///   instances of those types always have a contiguous block of memory as
@@ -563,9 +556,6 @@
   ///   If `n` is negative, this is the same value as the result of `-n` calls
   ///   to `index(before:)`.
   ///
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1)
   public func index(_ i: Int, offsetBy n: Int) -> Int {
     // NOTE: this is a manual specialization of index movement for a Strideable
@@ -660,7 +650,9 @@
 
   /// Accesses the element at the specified position.
   ///
-  /// For example:
+  /// The following example uses indexed subscripting to update an array's
+  /// second element. After assigning the new value (`"Butler"`) at a specific
+  /// position, that value is immediately available at that same position.
   ///
   ///     var streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
   ///     streets[1] = "Butler"
@@ -794,7 +786,8 @@
     buffer._copyContents(
       subRange: Range(buffer.indices),
       initializing: newBuffer.firstElementAddress)
-    buffer = _Buffer(newBuffer, shiftedToStartIndex: buffer.startIndex)
+    buffer = _Buffer(
+      _buffer: newBuffer, shiftedToStartIndex: buffer.startIndex)
   }
 
   @_semantics("array.make_mutable")
@@ -893,8 +886,8 @@
   /// Initialization from an existing buffer does not have "array.init"
   /// semantics because the caller may retain an alias to buffer.
   public // @testable
-  init(_buffer: _ContiguousArrayBuffer<Element>) {
-    self.init(_buffer: _Buffer(_buffer, shiftedToStartIndex: 0))
+  init(_buffer buffer: _ContiguousArrayBuffer<Element>) {
+    self.init(_buffer: _Buffer(_buffer: buffer, shiftedToStartIndex: 0))
   }
 %end
 
@@ -1039,7 +1032,7 @@
 
     self = ${Self}(
       _buffer: _Buffer(
-        s._copyToContiguousArray()._buffer,
+        _buffer: s._copyToContiguousArray()._buffer,
         shiftedToStartIndex: 0))
   }
 
@@ -1073,7 +1066,7 @@
   ) -> _Buffer {
     let newBuffer = _ContiguousArrayBuffer<Element>(
       uninitializedCount: 0, minimumCapacity: minimumCapacity)
-    return _Buffer(newBuffer, shiftedToStartIndex: 0)
+    return _Buffer(_buffer: newBuffer, shiftedToStartIndex: 0)
   }
 
   /// Construct a ${Self} of `count` uninitialized elements.
@@ -1126,7 +1119,8 @@
         storage, to: _ContiguousArrayStorage<Element>.self))
     
     return (
-      Array(_buffer: _Buffer(innerBuffer, shiftedToStartIndex: 0)),
+      Array(
+        _buffer: _Buffer(_buffer: innerBuffer, shiftedToStartIndex: 0)),
         innerBuffer.firstElementAddress)
   }
 
@@ -1211,7 +1205,8 @@
       _buffer._copyContents(
         subRange: Range(_buffer.indices),
         initializing: newBuffer.firstElementAddress)
-      _buffer = _Buffer(newBuffer, shiftedToStartIndex: _buffer.startIndex)
+      _buffer = _Buffer(
+        _buffer: newBuffer, shiftedToStartIndex: _buffer.startIndex)
     }
     _sanityCheck(capacity >= minimumCapacity)
   }
@@ -1258,13 +1253,25 @@
 
   /// Adds a new element at the end of the array.
   ///
+  /// Use this method to append a single element to the end of a mutable array.
+  ///
+  ///     var numbers = [1, 2, 3, 4, 5]
+  ///     numbers.append(100)
+  ///     print(numbers)
+  ///     // Prints "[1, 2, 3, 4, 5, 100]"
+  ///
+  /// Because arrays increase their allocated capacity using an exponential
+  /// strategy, appending a single element to an array is an O(1) operation
+  /// when averaged over many calls to the `append(_:)` method. When an array
+  /// has additional capacity and is not sharing its storage with another
+  /// instance, appending an element is O(1). When an array needs to
+  /// reallocate storage before appending or its storage is shared with
+  /// another copy, appending is O(*n*), where *n* is the length of the array.
+  ///
   /// - Parameter newElement: The element to append to the array.
   ///
-  /// - Complexity: Appending an element to the array averages to O(1) over
-  ///   many additions. When the array needs to reallocate storage before
-  ///   appending or its storage is shared with another copy, appending an
-  ///   element is O(*n*), where *n* is the length of the array. If the array
-  ///   uses a bridged `NSArray` instance as its storage, the efficiency is
+  /// - Complexity: Amortized O(1) over many additions. If the array uses a
+  ///   bridged `NSArray` instance as its storage, the efficiency is
   ///   unspecified.
   public mutating func append(_ newElement: Element) {
     _makeUniqueAndReserveCapacityIfNotUnique()
@@ -1275,8 +1282,8 @@
 
   /// Adds the elements of a sequence to the end of the array.
   ///
-  /// Use this method to append the elements of a sequence to the end of a
-  /// collection. This example appends the elements of a `Range<Int>` instance
+  /// Use this method to append the elements of a sequence to the end of an
+  /// array. This example appends the elements of a `Range<Int>` instance
   /// to an array of integers.
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
@@ -1307,7 +1314,7 @@
   /// Adds the elements of a collection to the end of the array.
   ///
   /// Use this method to append the elements of a collection to the end of this
-  /// collection. This example appends the elements of a `Range<Int>` instance
+  /// array. This example appends the elements of a `Range<Int>` instance
   /// to an array of integers.
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
@@ -1341,7 +1348,13 @@
 %if Self == 'ArraySlice':
   /// Removes and returns the last element of the array.
   ///
-  /// The array must not be empty.
+  /// The array must not be empty. This example removes the last number from an
+  /// array of `Double` values.
+  ///
+  ///     var measurements: [Double] = [1.1, 1.5, 2.9, 1.2, 1.5, 1.3, 1.2]
+  ///     let removed = measurements.removeLast()
+  ///     print(measurements)
+  ///     // Prints "[1.1, 1.5, 2.9, 1.2, 1.5, 1.3]"
   ///
   /// - Returns: The element that was removed.
   public mutating func _customRemoveLast() -> Element? {
@@ -1923,7 +1936,7 @@
     let tailEnd = source.endIndex
     source._copyContents(subRange: tailStart..<tailEnd, initializing: newEnd)
   }
-  source = _Buffer(dest, shiftedToStartIndex: source.startIndex)
+  source = _Buffer(_buffer: dest, shiftedToStartIndex: source.startIndex)
 }
 
 internal struct _InitializePointer<T> : _PointerFunction {
@@ -2081,6 +2094,11 @@
 
 #if _runtime(_ObjC)
 extension Array {
+  public // @SPI(Foundation)
+  func _bridgeToObjectiveCImpl() -> AnyObject {
+    return _buffer._asCocoaArray()
+  }
+
   /// Tries to downcast the source `NSArray` as our native buffer type.
   /// If it succeeds, creates a new `Array` around it and returns that.
   /// Returns `nil` otherwise.
@@ -2144,7 +2162,7 @@
   init(_startIndex: Int) {
     self.init(
       _buffer: _Buffer(
-        ContiguousArray()._buffer,
+        _buffer: ContiguousArray()._buffer,
         shiftedToStartIndex: _startIndex))
   }
 }
diff --git a/stdlib/public/core/Assert.swift b/stdlib/public/core/Assert.swift
index efc9ad8..7b007ad 100644
--- a/stdlib/public/core/Assert.swift
+++ b/stdlib/public/core/Assert.swift
@@ -10,23 +10,33 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Traditional C-style assert with an optional message.
+/// Performs a traditional C-style assert with an optional message.
 ///
-/// Use this function for internal sanity checks that are active
-/// during testing but do not impact performance of shipping code.
-/// To check for invalid usage in Release builds; see `precondition`.
+/// Use this function for internal sanity checks that are active during testing
+/// but do not impact performance of shipping code. To check for invalid usage
+/// in Release builds, see `precondition(_:_:file:line:)`.
 ///
-/// * In playgrounds and -Onone builds (the default for Xcode's Debug
-///   configuration): if `condition` evaluates to false, stop program
+/// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
+///   configuration): If `condition` evaluates to `false`, stop program
 ///   execution in a debuggable state after printing `message`.
 ///
-/// * In -O builds (the default for Xcode's Release configuration),
+/// * In `-O` builds (the default for Xcode's Release configuration),
 ///   `condition` is not evaluated, and there are no effects.
 ///
-/// * In -Ounchecked builds, `condition` is not evaluated, but the
-///   optimizer may assume that it *would* evaluate to `true`. Failure
-///   to satisfy that assumption in -Ounchecked builds is a serious
-///   programming error.
+/// * In `-Ounchecked` builds, `condition` is not evaluated, but the optimizer
+///   may assume that it *always* evaluates to `true`. Failure to satisfy that
+///   assumption is a serious programming error.
+///
+/// - Parameters:
+///   - condition: The condition to test. `condition` is only evaluated in
+///     playgrounds and `-Onone` builds.
+///   - message: A string to print if `condition` is evaluated to `false`. The
+///     default is an empty string.
+///   - file: The file name to print with `message` if the assertion fails. The
+///     default is the file where `assert(_:_:file:line:)` is called.
+///   - line: The line number to print along with `message` if the assertion
+///     fails. The default is the line number where `assert(_:_:file:line:)`
+///     is called.
 @_transparent
 public func assert(
   _ condition: @autoclosure () -> Bool,
@@ -42,22 +52,33 @@
   }
 }
 
-/// Check a necessary condition for making forward progress.
+/// Checks a necessary condition for making forward progress.
 ///
-/// Use this function to detect conditions that must prevent the
-/// program from proceeding even in shipping code.
+/// Use this function to detect conditions that must prevent the program from
+/// proceeding, even in shipping code.
 ///
-/// * In playgrounds and -Onone builds (the default for Xcode's Debug
-///   configuration): if `condition` evaluates to false, stop program
+/// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
+///   configuration): If `condition` evaluates to `false`, stop program
 ///   execution in a debuggable state after printing `message`.
 ///
-/// * In -O builds (the default for Xcode's Release configuration):
-///   if `condition` evaluates to false, stop program execution.
+/// * In `-O` builds (the default for Xcode's Release configuration): If
+///   `condition` evaluates to `false`, stop program execution.
 ///
-/// * In -Ounchecked builds, `condition` is not evaluated, but the
-///   optimizer may assume that it *would* evaluate to `true`. Failure
-///   to satisfy that assumption in -Ounchecked builds is a serious
-///   programming error.
+/// * In `-Ounchecked` builds, `condition` is not evaluated, but the optimizer
+///   may assume that it *always* evaluates to `true`. Failure to satisfy that
+///   assumption is a serious programming error.
+///
+/// - Parameters:
+///   - condition: The condition to test. `condition` is not evaluated in
+///     `-Ounchecked` builds.
+///   - message: A string to print if `condition` is evaluated to `false` in a
+///     playground or `-Onone` build. The default is an empty string.
+///   - file: The file name to print with `message` if the precondition fails.
+///     The default is the file where `precondition(_:_:file:line:)` is
+///     called.
+///   - line: The line number to print along with `message` if the assertion
+///     fails. The default is the line number where
+///     `precondition(_:_:file:line:)` is called.
 @_transparent
 public func precondition(
   _ condition: @autoclosure () -> Bool,
@@ -76,24 +97,31 @@
   }
 }
 
-/// Indicate that an internal sanity check failed.
+/// Indicates that an internal sanity check failed.
 ///
-/// Use this function to stop the program, without impacting the
-/// performance of shipping code, when control flow is not expected to
-/// reach the call (e.g. in the `default` case of a `switch` where you
-/// have knowledge that one of the other cases must be satisfied). To
-/// protect code from invalid usage in Release builds; see
-/// `preconditionFailure`.
+/// Use this function to stop the program, without impacting the performance of
+/// shipping code, when control flow is not expected to reach the call---for
+/// example, in the `default` case of a `switch` where you have knowledge that
+/// one of the other cases must be satisfied. To protect code from invalid
+/// usage in Release builds, see `preconditionFailure(_:file:line:)`.
 ///
 /// * In playgrounds and -Onone builds (the default for Xcode's Debug
-///   configuration) stop program execution in a debuggable state
-///   after printing `message`.
+///   configuration), stop program execution in a debuggable state after
+///   printing `message`.
 ///
 /// * In -O builds, has no effect.
 ///
-/// * In -Ounchecked builds, the optimizer may assume that this
-///   function will never be called. Failure to satisfy that assumption
-///   is a serious programming error.
+/// * In -Ounchecked builds, the optimizer may assume that this function is
+///   never called. Failure to satisfy that assumption is a serious
+///   programming error.
+///
+/// - Parameters:
+///   - message: A string to print in a playground or `-Onone` build. The
+///     default is an empty string.
+///   - file: The file name to print with `message`. The default is the file
+///     where `assertionFailure(_:file:line:)` is called.
+///   - line: The line number to print along with `message`. The default is the
+///     line number where `assertionFailure(_:file:line:)` is called.
 @inline(__always)
 public func assertionFailure(
   _ message: @autoclosure () -> String = String(),
@@ -108,21 +136,30 @@
   }
 }
 
-/// Indicate that a precondition was violated.
+/// Indicates that a precondition was violated.
 ///
-/// Use this function to stop the program when control flow can only
-/// reach the call if your API was improperly used.
+/// Use this function to stop the program when control flow can only reach the
+/// call if your API was improperly used. This function's effects vary
+/// depending on the build flag used:
 ///
-/// * In playgrounds and -Onone builds (the default for Xcode's Debug
-///   configuration), stop program execution in a debuggable state
-///   after printing `message`.
+/// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
+///   configuration), stops program execution in a debuggable state after
+///   printing `message`.
 ///
-/// * In -O builds (the default for Xcode's Release configuration),
-///   stop program execution.
+/// * In `-O` builds (the default for Xcode's Release configuration), stops
+///   program execution.
 ///
-/// * In -Ounchecked builds, the optimizer may assume that this
-///   function will never be called. Failure to satisfy that assumption
-///   is a serious programming error.
+/// * In `-Ounchecked` builds, the optimizer may assume that this function is
+///   never called. Failure to satisfy that assumption is a serious
+///   programming error.
+///
+/// - Parameters:
+///   - message: A string to print in a playground or `-Onone` build. The
+///     default is an empty string.
+///   - file: The file name to print with `message`. The default is the file
+///     where `preconditionFailure(_:file:line:)` is called.
+///   - line: The line number to print along with `message`. The default is the
+///     line number where `preconditionFailure(_:file:line:)` is called.
 @_transparent
 public func preconditionFailure(
   _ message: @autoclosure () -> String = String(),
@@ -138,7 +175,14 @@
   _conditionallyUnreachable()
 }
 
-/// Unconditionally print a `message` and stop execution.
+/// Unconditionally prints a given message and stops execution.
+///
+/// - Parameters:
+///   - message: The string to print. The default is an empty string.
+///   - file: The file name to print with `message`. The default is the file
+///     where `fatalError(_:file:line:)` is called.
+///   - line: The line number to print along with `message`. The default is the
+///     line number where `fatalError(_:file:line:)` is called.
 @_transparent
 public func fatalError(
   _ message: @autoclosure () -> String = String(),
diff --git a/stdlib/public/core/CTypes.swift b/stdlib/public/core/CTypes.swift
index 94d5329..cd74a0d 100644
--- a/stdlib/public/core/CTypes.swift
+++ b/stdlib/public/core/CTypes.swift
@@ -86,64 +86,62 @@
     self._rawValue = v
   }
 
-  /// Construct an `OpaquePointer` from a given address in memory.
+  /// Creates an `OpaquePointer` from a given address in memory.
   @_transparent
   public init?(bitPattern: Int) {
     if bitPattern == 0 { return nil }
     self._rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
   }
 
-  /// Construct an `OpaquePointer` from a given address in memory.
+  /// Creates an `OpaquePointer` from a given address in memory.
   @_transparent
   public init?(bitPattern: UInt) {
     if bitPattern == 0 { return nil }
     self._rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
   }
 
-  /// Convert a typed `UnsafePointer` to an opaque C pointer.
+  /// Converts a typed `UnsafePointer` to an opaque C pointer.
   @_transparent
   public init<T>(_ from: UnsafePointer<T>) {
     self._rawValue = from._rawValue
   }
 
-  /// Convert a typed `UnsafePointer` to an opaque C pointer.
+  /// Converts a typed `UnsafePointer` to an opaque C pointer.
   ///
-  /// Returns nil if `from` is nil.
+  /// The result is `nil` if `from` is `nil`.
   @_transparent
   public init?<T>(_ from: UnsafePointer<T>?) {
     guard let unwrapped = from else { return nil }
     self.init(unwrapped)
   }
 
-  /// Convert a typed `UnsafeMutablePointer` to an opaque C pointer.
+  /// Converts a typed `UnsafeMutablePointer` to an opaque C pointer.
   @_transparent
   public init<T>(_ from: UnsafeMutablePointer<T>) {
     self._rawValue = from._rawValue
   }
 
-  /// Convert a typed `UnsafeMutablePointer` to an opaque C pointer.
+  /// Converts a typed `UnsafeMutablePointer` to an opaque C pointer.
   ///
-  /// Returns nil if `from` is nil.
+  /// The result is `nil` if `from` is `nil`.
   @_transparent
   public init?<T>(_ from: UnsafeMutablePointer<T>?) {
     guard let unwrapped = from else { return nil }
     self.init(unwrapped)
   }
 
-  /// The hash value.
+  /// The pointer's hash value.
   ///
-  /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
-  ///
-  /// - Note: The hash value is not guaranteed to be stable across
-  ///   different invocations of the same program.  Do not persist the
-  ///   hash value across program runs.
+  /// The hash value is not guaranteed to be stable across different
+  /// invocations of the same program.  Do not persist the hash value across
+  /// program runs.
   public var hashValue: Int {
     return Int(Builtin.ptrtoint_Word(_rawValue))
   }
 }
 
 extension OpaquePointer : CustomDebugStringConvertible {
-  /// A textual representation of `self`, suitable for debugging.
+  /// A textual representation of the pointer, suitable for debugging.
   public var debugDescription: String {
     return _rawPointerToString(_rawValue)
   }
@@ -179,7 +177,7 @@
 }
 
 extension CVaListPointer : CustomDebugStringConvertible {
-  /// A textual representation of `self`, suitable for debugging.
+  /// A textual representation of the pointer, suitable for debugging.
   public var debugDescription: String {
     return value.debugDescription
   }
diff --git a/stdlib/public/core/ClosedRange.swift b/stdlib/public/core/ClosedRange.swift
index c4d0f82..c5dddee 100644
--- a/stdlib/public/core/ClosedRange.swift
+++ b/stdlib/public/core/ClosedRange.swift
@@ -385,7 +385,9 @@
 
 /// Returns a closed range that contains both of its bounds.
 ///
-/// For example:
+/// Use the closed range operator (`...`) to create a closed range of any type
+/// that conforms to the `Comparable` protocol. This example creates a
+/// `ClosedRange<Character>` from "a" up to, and including, "z".
 ///
 ///     let lowercase = "a"..."z"
 ///     print(lowercase.contains("z"))
@@ -404,12 +406,23 @@
 
 /// Returns a countable closed range that contains both of its bounds.
 ///
-/// For example:
-/// 
+/// Use the closed range operator (`...`) to create a closed range of any type
+/// that conforms to the `Strideable` protocol with an associated signed
+/// integer `Stride` type, such as any of the standard library's integer
+/// types. This example creates a `CountableClosedRange<Int>` from zero up to,
+/// and including, nine.
+///
 ///     let singleDigits = 0...9
 ///     print(singleDigits.contains(9))
 ///     // Prints "true"
 ///
+/// You can use sequence or collection methods on the `singleDigits` range.
+///
+///     print(singleDigits.count)
+///     // Prints "10"
+///     print(singleDigits.last)
+///     // Prints "9"
+///
 /// - Parameters:
 ///   - minimum: The lower bound for the range.
 ///   - maximum: The upper bound for the range.
diff --git a/stdlib/public/core/Collection.swift b/stdlib/public/core/Collection.swift
index 029f8f5..e69b144 100644
--- a/stdlib/public/core/Collection.swift
+++ b/stdlib/public/core/Collection.swift
@@ -174,9 +174,8 @@
   ///     print(s[i])
   ///     // Prints "t"
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
@@ -197,9 +196,9 @@
   /// unless that distance is beyond a given limiting index.
   ///
   /// The following example obtains an index advanced four positions from a
-  /// string's starting index and then prints the character at that position. The
-  /// operation doesn't require going beyond the limiting `s.endIndex` value,
-  /// so it succeeds.
+  /// string's starting index and then prints the character at that position.
+  /// The operation doesn't require going beyond the limiting `s.endIndex`
+  /// value, so it succeeds.
   ///
   ///     let s = "Swift"
   ///     if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
@@ -215,17 +214,17 @@
   ///     print(j)
   ///     // Prints "nil"
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection, unless the index passed as
+  /// `limit` prevents offsetting beyond those bounds.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
   ///   - n: The distance to offset `i`. `n` must not be negative unless the
   ///     collection conforms to the `BidirectionalCollection` protocol.
   ///   - limit: A valid index of the collection to use as a limit. If `n > 0`,
-  ///     `limit` has no effect if it is less than `i`. Likewise, if `n < 0`,
-  ///     `limit` has no effect if it is greater than `i`.
+  ///     a limit that is less than `i` has no effect. Likewise, if `n < 0`, a
+  ///     limit that is greater than `i` has no effect.
   /// - Returns: An index offset by `n` from the index `i`, unless that index
   ///   would be beyond `limit` in the direction of movement. In that case,
   ///   the method returns `nil`.
@@ -240,11 +239,10 @@
 
   /// Offsets the given index by the specified distance.
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection.
   ///
-  /// - Parameters
+  /// - Parameters:
   ///   - i: A valid index of the collection.
   ///   - n: The distance to offset `i`. `n` must not be negative unless the
   ///     collection conforms to the `BidirectionalCollection` protocol.
@@ -258,9 +256,9 @@
   /// Offsets the given index by the specified distance, or so that it equals
   /// the given limiting index.
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. Make
-  /// sure the value passed as `n` does not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection, unless the index passed as
+  /// `limit` prevents offsetting beyond those bounds.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
@@ -645,8 +643,10 @@
   /// Returns a subsequence from the start of the collection up to, but not
   /// including, the specified position.
   ///
-  /// The resulting subsequence *does not include* the element at the
-  /// position `end`.
+  /// The resulting subsequence *does not include* the element at the position
+  /// `end`. The following example searches for the index of the number `40`
+  /// in an array of integers, and then prints the prefix of the array up to,
+  /// but not including, that index:
   ///
   ///     let numbers = [10, 20, 30, 40, 50, 60]
   ///     if let i = numbers.index(of: 40) {
@@ -671,7 +671,9 @@
   /// Returns a subsequence from the specified position to the end of the
   /// collection.
   ///
-  /// For example:
+  /// The following example searches for the index of the number `40` in an
+  /// array of integers, and then prints the suffix of the array starting at
+  /// that index:
   ///
   ///     let numbers = [10, 20, 30, 40, 50, 60]
   ///     if let i = numbers.index(of: 40) {
@@ -695,7 +697,10 @@
   /// Returns a subsequence from the start of the collection through the
   /// specified position.
   ///
-  /// The resulting subsequence *includes* the element at the position `end`.
+  /// The resulting subsequence *includes* the element at the position `end`. 
+  /// The following example searches for the index of the number `40` in an
+  /// array of integers, and then prints the prefix of the array up to, and
+  /// including, that index:
   ///
   ///     let numbers = [10, 20, 30, 40, 50, 60]
   ///     if let i = numbers.index(of: 40) {
@@ -768,9 +773,8 @@
   ///     print(s[i])
   ///     // Prints "t"
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. Make
-  /// sure the value passed as `n` does not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
@@ -809,17 +813,17 @@
   ///     print(j)
   ///     // Prints "nil"
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection, unless the index passed as
+  /// `limit` prevents offsetting beyond those bounds.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
   ///   - n: The distance to offset `i`. `n` must not be negative unless the
   ///     collection conforms to the `BidirectionalCollection` protocol.
   ///   - limit: A valid index of the collection to use as a limit. If `n > 0`,
-  ///     `limit` has no effect if it is less than `i`. Likewise, if `n < 0`,
-  ///     `limit` has no effect if it is greater than `i`.
+  ///     a limit that is less than `i` has no effect. Likewise, if `n < 0`, a
+  ///     limit that is greater than `i` has no effect.
   /// - Returns: An index offset by `n` from the index `i`, unless that index
   ///   would be beyond `limit` in the direction of movement. In that case,
   ///   the method returns `nil`.
@@ -898,9 +902,8 @@
   ///     print(s[i])
   ///     // Prints "t"
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
@@ -941,17 +944,17 @@
   ///     print(j)
   ///     // Prints "nil"
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection, unless the index passed as
+  /// `limit` prevents offsetting beyond those bounds.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
   ///   - n: The distance to offset `i`. `n` must not be negative unless the
   ///     collection conforms to the `BidirectionalCollection` protocol.
   ///   - limit: A valid index of the collection to use as a limit. If `n > 0`,
-  ///     `limit` has no effect if it is less than `i`. Likewise, if `n < 0`,
-  ///     `limit` has no effect if it is greater than `i`.
+  ///     a limit that is less than `i` has no effect. Likewise, if `n < 0`, a
+  ///     limit that is greater than `i` has no effect.
   /// - Returns: An index offset by `n` from the index `i`, unless that index
   ///   would be beyond `limit` in the direction of movement. In that case,
   ///   the method returns `nil`.
@@ -968,11 +971,10 @@
 
   /// Offsets the given index by the specified distance.
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection.
   ///
-  /// - Parameters
+  /// - Parameters:
   ///   - i: A valid index of the collection.
   ///   - n: The distance to offset `i`. `n` must not be negative unless the
   ///     collection conforms to the `BidirectionalCollection` protocol.
@@ -988,9 +990,9 @@
   /// Offsets the given index by the specified distance, or so that it equals
   /// the given limiting index.
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. Make
-  /// sure the value passed as `n` does not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection, unless the index passed as
+  /// `limit` prevents offsetting beyond those bounds.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
@@ -1372,8 +1374,10 @@
   /// Returns a subsequence from the start of the collection up to, but not
   /// including, the specified position.
   ///
-  /// The resulting subsequence *does not include* the element at the
-  /// position `end`.
+  /// The resulting subsequence *does not include* the element at the position
+  /// `end`. The following example searches for the index of the number `40`
+  /// in an array of integers, and then prints the prefix of the array up to,
+  /// but not including, that index:
   ///
   ///     let numbers = [10, 20, 30, 40, 50, 60]
   ///     if let i = numbers.index(of: 40) {
@@ -1400,7 +1404,9 @@
   /// Returns a subsequence from the specified position to the end of the
   /// collection.
   ///
-  /// For example:
+  /// The following example searches for the index of the number `40` in an
+  /// array of integers, and then prints the suffix of the array starting at
+  /// that index:
   ///
   ///     let numbers = [10, 20, 30, 40, 50, 60]
   ///     if let i = numbers.index(of: 40) {
@@ -1414,8 +1420,8 @@
   ///     print(numbers.suffix(from: numbers.endIndex))
   ///     // Prints "[]"
   ///
-  /// - Parameter start: The index at which to start the resulting
-  ///   subsequence. `start` must be a valid index of the collection.
+  /// - Parameter start: The index at which to start the resulting subsequence.
+  ///   `start` must be a valid index of the collection.
   /// - Returns: A subsequence starting at the `start` position.
   ///
   /// - Complexity: O(1)
@@ -1426,8 +1432,10 @@
   /// Returns a subsequence from the start of the collection through the
   /// specified position.
   ///
-  /// The resulting subsequence *includes* the element at the position
-  /// `end`.
+  /// The resulting subsequence *includes* the element at the position `end`. 
+  /// The following example searches for the index of the number `40` in an
+  /// array of integers, and then prints the prefix of the array up to, and
+  /// including, that index:
   ///
   ///     let numbers = [10, 20, 30, 40, 50, 60]
   ///     if let i = numbers.index(of: 40) {
diff --git a/stdlib/public/core/CollectionAlgorithms.swift.gyb b/stdlib/public/core/CollectionAlgorithms.swift.gyb
index 2ad5fe4..3045ff5 100644
--- a/stdlib/public/core/CollectionAlgorithms.swift.gyb
+++ b/stdlib/public/core/CollectionAlgorithms.swift.gyb
@@ -127,9 +127,9 @@
   /// hold:
   ///
   /// - `areInIncreasingOrder(a, a)` is always `false`. (Irreflexivity)
-  /// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are both `true`,
-  ///   then `areInIncreasingOrder(a, c)` is also `true`. (Transitive
-  ///   comparability)
+  /// - If `areInIncreasingOrder(a, b)` and `areInIncreasingOrder(b, c)` are
+  ///   both `true`, then `areInIncreasingOrder(a, c)` is also `true`.
+  ///   (Transitive comparability)
   /// - Two elements are *incomparable* if neither is ordered before the other
   ///   according to the predicate. If `a` and `b` are incomparable, and `b`
   ///   and `c` are incomparable, then `a` and `c` are also incomparable.
diff --git a/stdlib/public/core/CollectionOfOne.swift b/stdlib/public/core/CollectionOfOne.swift
index 215fd33..5c458ad 100644
--- a/stdlib/public/core/CollectionOfOne.swift
+++ b/stdlib/public/core/CollectionOfOne.swift
@@ -39,7 +39,7 @@
 public struct CollectionOfOne<Element>
   : MutableCollection, RandomAccessCollection {
 
-  /// Construct an instance containing just `element`.
+  /// Creates an instance containing just `element`.
   public init(_ element: Element) {
     self._element = element
   }
@@ -81,7 +81,7 @@
     return IteratorOverOne(_elements: _element)
   }
 
-  /// Access the element at `position`.
+  /// Accesses the element at `position`.
   ///
   /// - Precondition: `position == 0`.
   public subscript(position: Int) -> Element {
diff --git a/stdlib/public/core/CompilerProtocols.swift b/stdlib/public/core/CompilerProtocols.swift
index b3f75e7..e3f3102 100644
--- a/stdlib/public/core/CompilerProtocols.swift
+++ b/stdlib/public/core/CompilerProtocols.swift
@@ -569,7 +569,7 @@
   associatedtype Key
   /// The value type of a dictionary literal.
   associatedtype Value
-  /// Create an instance initialized with `elements`.
+  /// Creates an instance initialized with the given key-value pairs.
   init(dictionaryLiteral elements: (Key, Value)...)
 }
 
diff --git a/stdlib/public/core/ContiguousArrayBuffer.swift b/stdlib/public/core/ContiguousArrayBuffer.swift
index 22b3c21..5e1b2be 100644
--- a/stdlib/public/core/ContiguousArrayBuffer.swift
+++ b/stdlib/public/core/ContiguousArrayBuffer.swift
@@ -115,7 +115,7 @@
   ) rethrows {
     if _isBridgedVerbatimToObjectiveC(Element.self) {
       let count = __manager.header.count
-      let elements = UnsafeMutableRawPointer(__manager._elementPointer)
+      let elements = UnsafeRawPointer(__manager._elementPointer)
         .assumingMemoryBound(to: AnyObject.self)
       defer { _fixLifetime(__manager) }
       try body(UnsafeBufferPointer(start: elements, count: count))
@@ -288,7 +288,7 @@
       _uncheckedUnsafeBufferObject: _emptyArrayStorage)
   }
 
-  public init(_ buffer: _ContiguousArrayBuffer, shiftedToStartIndex: Int) {
+  public init(_buffer buffer: _ContiguousArrayBuffer, shiftedToStartIndex: Int) {
     _sanityCheck(shiftedToStartIndex == 0, "shiftedToStartIndex must be 0")
     self = buffer
   }
diff --git a/stdlib/public/core/EmptyCollection.swift b/stdlib/public/core/EmptyCollection.swift
index 648699e..c8999bf 100644
--- a/stdlib/public/core/EmptyCollection.swift
+++ b/stdlib/public/core/EmptyCollection.swift
@@ -21,7 +21,7 @@
 ///
 /// - SeeAlso: `EmptyCollection<Element>`.
 public struct EmptyIterator<Element> : IteratorProtocol, Sequence {
-  /// Construct an instance.
+  /// Creates an instance.
   public init() {}
 
   /// Returns `nil`, indicating that there are no more elements.
@@ -42,7 +42,7 @@
   public typealias IndexDistance = Int
   public typealias SubSequence = EmptyCollection<Element>
 
-  /// Construct an instance.
+  /// Creates an instance.
   public init() {}
 
   /// Always zero, just like `endIndex`.
@@ -57,7 +57,7 @@
 
   /// Always traps.
   ///
-  /// EmptyCollection does not have any element indices, so it is not
+  /// `EmptyCollection` does not have any element indices, so it is not
   /// possible to advance indices.
   public func index(after i: Index) -> Index {
     _preconditionFailure("EmptyCollection can't advance indices")
@@ -65,22 +65,20 @@
 
   /// Always traps.
   ///
-  /// EmptyCollection does not have any element indices, so it is not
+  /// `EmptyCollection` does not have any element indices, so it is not
   /// possible to advance indices.
   public func index(before i: Index) -> Index {
     _preconditionFailure("EmptyCollection can't advance indices")
   }
 
   /// Returns an empty iterator.
-  ///
-  /// - Complexity: O(1).
   public func makeIterator() -> EmptyIterator<Element> {
     return EmptyIterator()
   }
 
-  /// Access the element at `position`.
+  /// Accesses the element at the given position.
   ///
-  /// Should never be called, since this collection is always empty.
+  /// Must never be called, since this collection is always empty.
   public subscript(position: Index) -> Element {
     get {
       _preconditionFailure("Index out of range")
diff --git a/stdlib/public/core/Equatable.swift b/stdlib/public/core/Equatable.swift
index fb26955..980cecb 100644
--- a/stdlib/public/core/Equatable.swift
+++ b/stdlib/public/core/Equatable.swift
@@ -184,10 +184,54 @@
 // Reference comparison
 //===----------------------------------------------------------------------===//
 
-/// Returns `true` iff `lhs` and `rhs` are references to the same object
-/// instance (in other words, are identical pointers).
+/// Returns a Boolean value indicating whether two references point to the same
+/// object instance.
 ///
-/// - SeeAlso: `Equatable`, `==`
+/// This operator tests whether two instances have the same identity, not the
+/// same value. For value equality, see the equal-to operator (`==`) and the
+/// `Equatable` protocol.
+///
+/// The following example defines an `IntegerRef` type; an integer type with
+/// reference semantics.
+///
+///     class IntegerRef: Equatable {
+///         let value: Int
+///         init(_ value: Int) {
+///             self.value = value
+///         }
+///     }
+///
+///     func ==(lhs: IntegerRef, rhs: IntegerRef) -> Bool {
+///         return lhs.value == rhs.value
+///     }
+///
+/// Because `IntegerRef` is a class, its instances can be compared using the
+/// identical-to operator (`===`). In addition, because `IntegerRef` conforms
+/// to the `Equatable` protocol, instances can also be compared using the
+/// equal-to operator (`==`).
+///
+///     let a = IntegerRef(10)
+///     let b = a
+///     print(a == b)
+///     // Prints "true"
+///     print(a === b)
+///     // Prints "true"
+///
+/// The identical-to operator (`===`) returns `false` when comparing two
+/// references to different objects instances, even if the two instances have
+/// the same value.
+///
+///     let c = IntegerRef(10)
+///     print(a == c)
+///     // Prints "true"
+///     print(a === c)
+///     // Prints "false"
+///
+/// - Parameters:
+///   - lhs: A reference to compare.
+///   - rhs: Another reference to compare.
+///
+/// - SeeAlso: `Equatable`, `==`, `!==`
 public func === (lhs: AnyObject?, rhs: AnyObject?) -> Bool {
   switch (lhs, rhs) {
   case let (l?, r?):
@@ -202,6 +246,18 @@
   }
 }
 
+/// Returns a Boolean value indicating whether two references point to
+/// different object instances.
+///
+/// This operator tests whether two instances have different identities, not
+/// different values. For value inequality, see the not-equal-to operator
+/// (`!=`) and the `Equatable` protocol.
+///
+/// - Parameters:
+///   - lhs: A reference to compare.
+///   - rhs: Another reference to compare.
+///
+/// - SeeAlso: `Equatable`, `===`, `!=`
 public func !== (lhs: AnyObject?, rhs: AnyObject?) -> Bool {
   return !(lhs === rhs)
 }
diff --git a/stdlib/public/core/ExistentialCollection.swift.gyb b/stdlib/public/core/ExistentialCollection.swift.gyb
index e673d7b..9d67ef4 100644
--- a/stdlib/public/core/ExistentialCollection.swift.gyb
+++ b/stdlib/public/core/ExistentialCollection.swift.gyb
@@ -43,32 +43,47 @@
 ///
 /// - SeeAlso: `AnySequence`
 public struct AnyIterator<Element> : IteratorProtocol {
-  /// Creates an iterator that wraps `base` but whose type depends only on the
-  /// type of `I.Element`.
+  /// Creates an iterator that wraps a base iterator but whose type depends
+  /// only on the base iterator's element type.
   ///
-  /// Example:
+  /// You can use `AnyIterator` to hide the type signature of a more complex
+  /// iterator. For example, the `digits()` function in the following example
+  /// creates an iterator over a collection that lazily maps the elements of a
+  /// `CountableRange<Int>` instance to strings. Instead of returning an
+  /// iterator with a type that encapsulates the implementation of the
+  /// collection, the `digits()` function first wraps the iterator in an
+  /// `AnyIterator` instance.
   ///
   ///     func digits() -> AnyIterator<String> {
-  ///       let lazyStrings = (0..<10).lazy.map { String($0) }
+  ///         let lazyStrings = (0..<10).lazy.map { String($0) }
+  ///         let iterator:
+  ///             LazyMapIterator<IndexingIterator<CountableRange<Int>>, String>
+  ///             = lazyStrings.makeIterator()
   ///
-  ///       // This is a really complicated type of no interest to our
-  ///       // clients.
-  ///       let iterator: MapSequenceIterator<RangeIterator<Int>, String>
-  ///         = lazyStrings.makeIterator()
-  ///       return AnyIterator(iterator)
+  ///         return AnyIterator(iterator)
   ///     }
+  ///
+  /// - Parameter base: An iterator to type-erase.
   public init<I : IteratorProtocol>(_ base: I) where I.Element == Element {
     self._box = _IteratorBox(base)
   }
 
-  /// Creates an iterator whose `next` method invokes `body` and returns the
-  /// result.
+  /// Creates an iterator that wraps the given closure in its `next()` method.
   ///
-  /// Example:
+  /// The following example creates an iterator that counts up from the initial
+  /// value of an integer `x` to 15:
   ///
   ///     var x = 7
-  ///     let iterator = AnyIterator { x < 15 ? x++ : nil }
-  ///     let a = Array(iterator) // [ 7, 8, 9, 10, 11, 12, 13, 14 ]
+  ///     let iterator: AnyIterator<Int> = AnyIterator {
+  ///         defer { x += 1 }
+  ///         return x < 15 ? x : nil
+  ///     }
+  ///     let a = Array(iterator)
+  ///     // a == [7, 8, 9, 10, 11, 12, 13, 14]
+  ///
+  /// - Parameter body: A closure that returns an optional element. `body` is
+  ///   executed each time the `next()` method is called on the resulting
+  ///   iterator.
   public init(_ body: @escaping () -> Element?) {
     self._box = _IteratorBox(_ClosureBasedIterator(body))
   }
@@ -527,9 +542,9 @@
 
 /// A type-erased sequence.
 ///
-/// Forwards operations to an arbitrary underlying sequence having the
-/// same `Element` type, hiding the specifics of the underlying
-/// `Sequence`.
+/// An instance of `AnySequence` forwards its operations to an underlying base
+/// sequence having the same `Element` type, hiding the specifics of the
+/// underlying sequence.
 ///
 /// - SeeAlso: `AnyIterator`
 public struct AnySequence<Element> : Sequence {
@@ -565,8 +580,6 @@
 %   else:
   /// Returns an iterator over the elements of this collection.
 %   end
-  ///
-  /// - Complexity: O(1).
   public func makeIterator() -> AnyIterator<Element> {
     return _box._makeIterator()
   }
@@ -680,8 +693,7 @@
   }
 }
 
-/// A wrapper over an underlying index that hides
-/// the specific underlying type.
+/// A wrapper over an underlying index that hides the specific underlying type.
 ///
 /// - SeeAlso: `AnyCollection`
 public struct AnyIndex {
@@ -702,15 +714,27 @@
 }
 
 extension AnyIndex : Comparable {
-  /// Returns `true` iff `lhs` and `rhs` wrap equal underlying indices.
+  /// Returns a Boolean value indicating whether two indices wrap equal
+  /// underlying indices.
   ///
-  /// - Precondition: The types of indices wrapped by `lhs` and `rhs` are
-  ///   identical.
+  /// The types of the two underlying indices must be identical.
+  ///
+  /// - Parameters:
+  ///   - lhs: An index to compare.
+  ///   - rhs: Another index to compare.
   public static func == (lhs: AnyIndex, rhs: AnyIndex) -> Bool {
     _precondition(lhs._typeID == rhs._typeID, "base index types differ")
     return lhs._box._isEqual(to: rhs._box)
   }
 
+  /// Returns a Boolean value indicating whether the first argument represents a
+  /// position before the second argument.
+  ///
+  /// The types of the two underlying indices must be identical.
+  ///
+  /// - Parameters:
+  ///   - lhs: An index to compare.
+  ///   - rhs: Another index to compare.
   public static func < (lhs: AnyIndex, rhs: AnyIndex) -> Bool {
     _precondition(lhs._typeID == rhs._typeID, "base index types differ")
     return lhs._box._isLess(than: rhs._box)
@@ -733,9 +757,9 @@
 /// A type-erased wrapper over any collection with indices that
 /// support ${Traversal.lower().replace('omacc', 'om acc')} traversal.
 ///
-/// Forwards operations to an arbitrary underlying collection having the
+/// An `${Self}` instance forwards its operations to a base collection having the
 /// same `Element` type, hiding the specifics of the underlying
-/// `Collection`.
+/// collection.
 ///
 /// - SeeAlso: ${', '.join('`Any%sCollection`' % t for t in (2 * TRAVERSALS)[ti + 1 : ti + 3]) }
 public struct ${Self}<Element>
@@ -747,8 +771,9 @@
 
 %   for SubTraversal in TRAVERSALS[ti:]:
 %     SubProtocol = collectionForTraversal(SubTraversal)
-  /// Creates an `${Self}` that
-  /// stores `base` as its underlying collection.
+  /// Creates a type-erased collection that wraps the given collection.
+  ///
+  /// - Parameter base: The collection to wrap.
   ///
   /// - Complexity: O(1).
   public init<C : ${SubProtocol}>(_ base: C)
@@ -775,12 +800,9 @@
       _base: base)
   }
 
-  /// Creates an `Any${Traversal}Collection` having the same underlying
-  /// collection as `other`.
+  /// Creates an `${Self}` having the same underlying collection as `other`.
   ///
-  /// - Postcondition: The result is `===` to `other`.
-  ///
-  /// - Complexity: O(1).
+  /// - Complexity: O(1)
   public init(
     _ other: Any${SubProtocol}<Element>
   ) {
@@ -789,12 +811,12 @@
 %   end
 
 %   for SuperTraversal in TRAVERSALS[:ti]:
-  /// If the underlying collection stored by `other` satisfies
-  /// `${SelfProtocol}`, creates an `${Self}` having the same
-  /// underlying collection as `other`.  Otherwise, the result is
-  /// `nil`.
+  /// Creates an `${Self}` having the same underlying collection as `other`.
   ///
-  /// - Complexity: O(1).
+  /// If the underlying collection stored by `other` does not satisfy
+  /// `${SelfProtocol}`, the result is `nil`.
+  ///
+  /// - Complexity: O(1)
   public init?(
     _ other: Any${collectionForTraversal(SuperTraversal)}<Element>
   ) {
@@ -906,7 +928,7 @@
 
   /// The number of elements.
   ///
-  /// - Complexity: ${'O(1)' if Traversal == 'RandomAccess' else 'O(N)'}.
+  /// - Complexity: ${'O(1)' if Traversal == 'RandomAccess' else 'O(N)'}
   public var count: IntMax {
     return _box._count
   }
diff --git a/stdlib/public/core/Filter.swift.gyb b/stdlib/public/core/Filter.swift.gyb
index 5212bca..e7edb1a 100644
--- a/stdlib/public/core/Filter.swift.gyb
+++ b/stdlib/public/core/Filter.swift.gyb
@@ -12,7 +12,6 @@
 
 %{
 from gyb_stdlib_support import (
-    TRAVERSALS,
     collectionForTraversal,
     sliceTypeName
 )
@@ -187,7 +186,7 @@
 
   public typealias IndexDistance = Base.IndexDistance
 
-  /// Construct an instance containing the elements of `base` that
+  /// Creates an instance containing the elements of `base` that
   /// satisfy `isIncluded`.
   public // @testable
   init(
@@ -256,7 +255,7 @@
   }
 %   end
 
-  /// Access the element at `position`.
+  /// Accesses the element at `position`.
   ///
   /// - Precondition: `position` is a valid position in `self` and
   /// `position != endIndex`.
diff --git a/stdlib/public/core/Flatten.swift.gyb b/stdlib/public/core/Flatten.swift.gyb
index bc30595..9bc5506 100644
--- a/stdlib/public/core/Flatten.swift.gyb
+++ b/stdlib/public/core/Flatten.swift.gyb
@@ -138,7 +138,8 @@
   Elements.Iterator.Element == Iterator.Element,
   Iterator.Element : Sequence {
 
-  /// A concatenation of the elements of `self`.
+  /// Returns a lazy sequence that concatenates the elements of this sequence of
+  /// sequences.
   public func joined() -> LazySequence<
     FlattenSequence<Elements>
   > {
@@ -328,7 +329,7 @@
   }
 % end
 
-  /// Access the element at `position`.
+  /// Accesses the element at `position`.
   ///
   /// - Precondition: `position` is a valid position in `self` and
   ///   `position != endIndex`.
diff --git a/stdlib/public/core/FloatingPointParsing.swift.gyb b/stdlib/public/core/FloatingPointParsing.swift.gyb
index 8c53115..e113b57 100644
--- a/stdlib/public/core/FloatingPointParsing.swift.gyb
+++ b/stdlib/public/core/FloatingPointParsing.swift.gyb
@@ -46,7 +46,7 @@
   /// Creates a new instance from the given string.
   ///
   /// The string passed as `text` can represent a real number in decimal or
-  /// hexidecimal format or special floating-point values for infinty and NaN
+  /// hexadecimal format or special floating-point values for infinty and NaN
   /// ("not a number").
   ///
   /// The given string may begin with a plus or minus sign character (`+` or
@@ -71,17 +71,17 @@
   ///       let e = ${Self}("2837.5e-2")
   ///       // e == 28.375
   ///
-  /// - A *hexidecimal value* contains the significand, either `0X` or `0x`,
-  ///   followed by a sequence of hexidecimal digits. The significand may
+  /// - A *hexadecimal value* contains the significand, either `0X` or `0x`,
+  ///   followed by a sequence of hexadecimal digits. The significand may
   ///   include a decimal point.
   ///
   ///       let f = ${Self}("0x1c.6")
   ///       // f == 28.375
   ///
-  ///   A hexidecimal value may also include an exponent following the
+  ///   A hexadecimal value may also include an exponent following the
   ///   significand, indicating the power of 2 by which the significand should
   ///   be multiplied. If included, the exponent is separated by a single
-  ///   character `p` or `P` and consists of an optional plus or minus sign
+  ///   character, `p` or `P`, and consists of an optional plus or minus sign
   ///   character and a sequence of decimal digits.
   ///
   ///       let g = ${Self}("0x1.c6p4")
@@ -102,9 +102,9 @@
   ///       // n?.isNaN == true
   ///       // n?.sign == .minus
   ///
-  ///   An NaN value may also include a payload in parentheses following the
+  ///   A NaN value may also include a payload in parentheses following the
   ///   `"nan"` keyword. The payload consists of a sequence of decimal digits,
-  ///   or the characters `0X` or `0x` followed by a sequence of hexidecimal
+  ///   or the characters `0X` or `0x` followed by a sequence of hexadecimal
   ///   digits. If the payload contains any other characters, it is ignored.
   ///   If the value of the payload is larger than can be stored as the
   ///   payload of a `${Self}.nan`, the least significant bits are used.
diff --git a/stdlib/public/core/HashedCollections.swift.gyb b/stdlib/public/core/HashedCollections.swift.gyb
index 3818421..b7ebc61 100644
--- a/stdlib/public/core/HashedCollections.swift.gyb
+++ b/stdlib/public/core/HashedCollections.swift.gyb
@@ -520,7 +520,8 @@
   /// Returns a Boolean value that indicates whether the given element exists
   /// in the set.
   ///
-  /// For example:
+  /// This example uses the `contains(_:)` method to test whether an integer is
+  /// a member of a set of prime numbers.
   ///
   ///     let primes: Set = [2, 3, 5, 7]
   ///     let x = 5
@@ -611,7 +612,7 @@
   
   /// Removes the specified element from the set.
   ///
-  /// For example:
+  /// This example removes the element `"sugar"` from a set of ingredients.
   ///
   ///     var ingredients: Set = ["cocoa beans", "sugar", "cocoa butter", "salt"]
   ///     let toRemove = "sugar"
@@ -871,7 +872,8 @@
   /// Returns a Boolean value that indicates whether the set has no members in
   /// common with the given sequence.
   ///
-  /// For example:
+  /// In the following example, the `employees` set is disjoint with the
+  /// elements of the `visitors` array because no name appears in both.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let visitors = ["Marcia", "Nathaniel", "Olivia"]
@@ -891,7 +893,8 @@
   /// Returns a new set with the elements of both this set and the given
   /// sequence.
   ///
-  /// For example:
+  /// In the following example, the `attendeesAndVisitors` set is made up
+  /// of the elements of the `attendees` set and the `visitors` array:
   ///
   ///     let attendees: Set = ["Alicia", "Bethany", "Diana"]
   ///     let visitors = ["Marcia", "Nathaniel"]
@@ -901,8 +904,7 @@
   ///
   /// If the set already contains one or more elements that are also in
   /// `other`, the existing members are kept. If `other` contains multiple
-  /// instances of equivalent elements, only the first instance is kept. For
-  /// example:
+  /// instances of equivalent elements, only the first instance is kept.
   ///
   ///     let initialIndices = Set(0..<5)
   ///     let expandedIndices = initialIndices.union([2, 3, 6, 6, 7, 7])
@@ -941,7 +943,8 @@
   /// Returns a new set containing the elements of this set that do not occur
   /// in the given sequence.
   ///
-  /// For example:
+  /// In the following example, the `nonNeighbors` set is made up of the
+  /// elements of the `employees` set that are not elements of `neighbors`:
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -965,7 +968,9 @@
 
   /// Removes the elements of the given sequence from the set.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// also elements of the `neighbors` array are removed. In particular, the
+  /// names `"Bethany"` and `"Eric"` are removed from `employees`.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -989,7 +994,10 @@
   /// Returns a new set with the elements that are common to both this set and
   /// the given sequence.
   ///
-  /// For example:
+  /// In the following example, the `bothNeighborsAndEmployees` set is made up
+  /// of the elements that are in *both* the `employees` and `neighbors` sets.
+  /// Elements that are only in one or the other are left out of the result of
+  /// the intersection.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -1007,7 +1015,9 @@
 
   /// Removes the elements of the set that aren't also in the given sequence.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// not also members of the `neighbors` set are removed. In particular, the
+  /// names `"Alicia"`, `"Chris"`, and `"Diana"` are removed.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -1037,7 +1047,10 @@
   /// Returns a new set with the elements that are either in this set or in the
   /// given sequence, but not in both.
   ///
-  /// For example:
+  /// In the following example, the `eitherNeighborsOrEmployees` set is made up
+  /// of the elements of the `employees` and `neighbors` sets that are not in
+  /// both `employees` *and* `neighbors`. In particular, the names `"Bethany"`
+  /// and `"Eric"` do not appear in `eitherNeighborsOrEmployees`.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
   ///     let neighbors = ["Bethany", "Eric", "Forlani"]
@@ -1057,7 +1070,12 @@
   /// Replace this set with the elements contained in this set or the given
   /// set, but not both.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// also members of `neighbors` are removed from `employees`, while the
+  /// elements of `neighbors` that are not members of `employees` are added to
+  /// `employees`. In particular, the names `"Alicia"`, `"Chris"`, and
+  /// `"Diana"` are removed from `employees` while the name `"Forlani"` is
+  /// added.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
   ///     let neighbors = ["Bethany", "Eric", "Forlani"]
@@ -5066,10 +5084,12 @@
 extension Set {
   /// Removes the elements of the given set from this set.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// also members of the `neighbors` set are removed. In particular, the
+  /// names `"Bethany"` and `"Eric"` are removed from `employees`.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
-  ///     let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
+  ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
   ///     employees.subtract(neighbors)
   ///     print(employees)
   ///     // Prints "["Diana", "Chris", "Alicia"]"
@@ -5079,19 +5099,19 @@
     _subtract(other)
   }
 
-  /// Returns a Boolean value that indicates whether this set is a subset of the
-  /// given set.
+  /// Returns a Boolean value that indicates whether this set is a subset of
+  /// the given set.
   ///
   /// Set *A* is a subset of another set *B* if every member of *A* is also a
   /// member of *B*.
   ///
-  ///     let employees = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
+  ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let attendees: Set = ["Alicia", "Bethany", "Diana"]
   ///     print(attendees.isSubset(of: employees))
   ///     // Prints "true"
   ///
-  /// - Parameter other: A sequence of elements. `possibleSuperset`
-  ///   must be finite.
+  /// - Parameter other: A sequence of elements. `possibleSuperset` must be
+  ///   finite.
   /// - Returns: `true` if the set is a subset of `possibleSuperset`;
   ///   otherwise, `false`.
   public func isSubset(of other: Set<Element>) -> Bool {
@@ -5120,7 +5140,8 @@
   /// Returns a Boolean value that indicates whether this set has no members in
   /// common with the given set.
   ///
-  /// For example:
+  /// In the following example, the `employees` set is disjoint with the
+  /// `visitors` set because no name appears in both sets.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let visitors: Set = ["Marcia", "Nathaniel", "Olivia"]
@@ -5142,7 +5163,8 @@
   /// Returns a new set containing the elements of this set that do not occur
   /// in the given set.
   ///
-  /// For example:
+  /// In the following example, the `nonNeighbors` set is made up of the
+  /// elements of the `employees` set that are not elements of `neighbors`:
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -5203,7 +5225,10 @@
   /// Returns a new set with the elements that are common to both this set and
   /// the given sequence.
   ///
-  /// For example:
+  /// In the following example, the `bothNeighborsAndEmployees` set is made up
+  /// of the elements that are in *both* the `employees` and `neighbors` sets.
+  /// Elements that are only in one or the other are left out of the result of
+  /// the intersection.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -5226,7 +5251,12 @@
   /// Removes the elements of the set that are also in the given sequence and
   /// adds the members of the sequence that are not already in the set.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// also members of `neighbors` are removed from `employees`, while the
+  /// elements of `neighbors` that are not members of `employees` are added to
+  /// `employees`. In particular, the names `"Alicia"`, `"Chris"`, and
+  /// `"Diana"` are removed from `employees` while the names `"Forlani"` and
+  /// `"Greta"` are added.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
diff --git a/stdlib/public/core/HashedCollectionsAnyHashableExtensions.swift.gyb b/stdlib/public/core/HashedCollectionsAnyHashableExtensions.swift.gyb
index 8844d49..18e3c0f 100644
--- a/stdlib/public/core/HashedCollectionsAnyHashableExtensions.swift.gyb
+++ b/stdlib/public/core/HashedCollectionsAnyHashableExtensions.swift.gyb
@@ -28,16 +28,6 @@
 // properly expressed in the language.
 extension Set {
   @inline(__always)
-  internal func _concreteElement_contains(_ member: Element) -> Bool {
-    return contains(member)
-  }
-
-  @inline(__always)
-  internal func _concreteElement_index(of member: Element) -> Index? {
-    return index(of: member)
-  }
-
-  @inline(__always)
   internal mutating func _concreteElement_insert(
     _ newMember: Element
   ) -> (inserted: Bool, memberAfterInsert: Element) {
@@ -61,18 +51,6 @@
 
 // FIXME(ABI)(compiler limitation): replace with `where Element == AnyHashable`.
 extension Set where Element : _AnyHashableProtocol {
-  public func contains<ConcreteElement : Hashable>(
-    _ member: ConcreteElement
-  ) -> Bool {
-    return _concreteElement_contains(AnyHashable(member) as! Element)
-  }
-
-  public func index<ConcreteElement : Hashable>(
-    of member: ConcreteElement
-  ) -> SetIndex<Element>? {
-    return _concreteElement_index(of: AnyHashable(member) as! Element)
-  }
-
   public mutating func insert<ConcreteElement : Hashable>(
     _ newMember: ConcreteElement
   ) -> (inserted: Bool, memberAfterInsert: ConcreteElement) {
@@ -107,11 +85,6 @@
 // FIXME: remove these trampolines when extensions below can be
 // properly expressed in the language.
 extension Dictionary {
-  @inline(__always)
-  internal func _concreteKey_index(forKey key: Key) -> Index? {
-    return index(forKey: key)
-  }
-
   internal subscript(_concreteKey key: Key) -> Value? {
     @inline(__always)
     get {
@@ -138,12 +111,6 @@
 
 // FIXME(ABI)(compiler limitation): replace with `where Element == AnyHashable`.
 extension Dictionary where Key : _AnyHashableProtocol {
-  public func index<ConcreteKey : Hashable>(forKey key: ConcreteKey)
-    -> DictionaryIndex<Key, Value>?
-  {
-    return _concreteKey_index(forKey: AnyHashable(key) as! Key)
-  }
-
   public subscript(_ key: _Hashable) -> Value? {
     // FIXME(ABI)(compiler limitation): replace this API with a
     // generic subscript.
diff --git a/stdlib/public/core/InputStream.swift b/stdlib/public/core/InputStream.swift
index 0dc48b9..6a839eb 100644
--- a/stdlib/public/core/InputStream.swift
+++ b/stdlib/public/core/InputStream.swift
@@ -12,15 +12,20 @@
 
 import SwiftShims
 
-/// Returns `Character`s read from standard input through the end of the
-/// current line or until EOF is reached, or `nil` if EOF has already been
-/// reached.
+/// Returns a string read from standard input through the end of the current
+/// line or until EOF is reached.
 ///
-/// If `strippingNewline` is `true`, newline characters and character
-/// combinations will be stripped from the result.  This is the default.
+/// Standard input is interpreted as `UTF-8`. Invalid bytes are replaced by
+/// Unicode [replacement characters][rc].
 ///
-/// Standard input is interpreted as `UTF-8`.  Invalid bytes
-/// will be replaced by Unicode [replacement characters](http://en.wikipedia.org/wiki/Specials_(Unicode_block)#Replacement_character).
+/// [rc]:
+/// http://en.wikipedia.org/wiki/Specials_(Unicode_block)#Replacement_character
+///
+/// - Parameter strippingNewline: If `true`, newline characters and character
+///   combinations are stripped from the result; otherwise, newline characters
+///   or character combinations are preserved. The default is `true`.
+/// - Returns: The string of characters read from standard input. If EOF has
+///   already been reached when `readLine()` is called, the result is `nil`.
 public func readLine(strippingNewline: Bool = true) -> String? {
   var linePtrVar: UnsafeMutablePointer<UInt8>? = nil
   var readBytes = swift_stdlib_readLine_stdin(&linePtrVar)
diff --git a/stdlib/public/core/Integers.swift.gyb b/stdlib/public/core/Integers.swift.gyb
index 4b7aebd..4d4357e 100644
--- a/stdlib/public/core/Integers.swift.gyb
+++ b/stdlib/public/core/Integers.swift.gyb
@@ -230,6 +230,7 @@
   public init?<T : FloatingPoint>(exactly source: T) {
     // FIXME(integers): implement
     fatalError()
+    return nil
   }
 
   public init<T : FloatingPoint>(_ source: T) {
diff --git a/stdlib/public/core/Join.swift b/stdlib/public/core/Join.swift
index d2bac36..f137972 100644
--- a/stdlib/public/core/Join.swift
+++ b/stdlib/public/core/Join.swift
@@ -18,7 +18,7 @@
 }
 
 /// An iterator that presents the elements of the sequences traversed
-/// by `Base`, concatenated using a given separator.
+/// by a base iterator, concatenated using a given separator.
 public struct JoinedIterator<Base : IteratorProtocol> : IteratorProtocol
   where Base.Element : Sequence {
 
@@ -86,7 +86,7 @@
   internal var _state: _JoinIteratorState = .start
 }
 
-/// A sequence that presents the elements of the `Base` sequences
+/// A sequence that presents the elements of a base sequence of sequences
 /// concatenated using a given separator.
 public struct JoinedSequence<Base : Sequence> : Sequence
   where Base.Iterator.Element : Sequence {
diff --git a/stdlib/public/core/LazyCollection.swift.gyb b/stdlib/public/core/LazyCollection.swift.gyb
index be2a22e..e0166ff 100644
--- a/stdlib/public/core/LazyCollection.swift.gyb
+++ b/stdlib/public/core/LazyCollection.swift.gyb
@@ -51,10 +51,10 @@
 /// - See also: `LazySequenceProtocol`, `LazyCollection`
 public struct ${Self}<Base : ${TraversalCollection}> : LazyCollectionProtocol {
 
-  /// The type of the underlying collection
+  /// The type of the underlying collection.
   public typealias Elements = Base
 
-  /// The underlying collection
+  /// The underlying collection.
   public var elements: Elements { return _base }
 
   /// A type that represents a valid position in the collection.
@@ -63,7 +63,7 @@
   /// "past the end" position that's not valid for use as a subscript.
   public typealias Index = Base.Index
   
-  /// Construct an instance with `base` as its underlying Collection
+  /// Creates an instance with `base` as its underlying Collection
   /// instance.
   internal init(_base: Base) {
     self._base = _base
@@ -134,7 +134,7 @@
     return _base.index(after: i)
   }
 
-  /// Access the element at `position`.
+  /// Accesses the element at `position`.
   ///
   /// - Precondition: `position` is a valid position in `self` and
   ///   `position != endIndex`.
@@ -150,7 +150,7 @@
     return ${Slice}(base: _base, bounds: bounds).lazy
   }
   
-  /// Returns `true` iff `self` is empty.
+  /// A Boolean value indicating whether the collection is empty.
   public var isEmpty: Bool {
     return _base.isEmpty
   }
diff --git a/stdlib/public/core/ManagedBuffer.swift b/stdlib/public/core/ManagedBuffer.swift
index 882f073..9dfd62d 100644
--- a/stdlib/public/core/ManagedBuffer.swift
+++ b/stdlib/public/core/ManagedBuffer.swift
@@ -450,28 +450,30 @@
 // FIXME: when our calling convention changes to pass self at +0,
 // inout should be dropped from the arguments to these functions.
 
-/// Returns `true` iff `object` is known to be a class instance with a single
-/// strong reference.
+/// Returns a Boolean value indicating whether the given object is a
+/// class instance known to have a single strong reference.
 ///
-/// * Does *not* modify `object`; the use of `inout` is an
-///   implementation artifact.
-/// * Weak references do not affect the result of this function.
-///
-/// Useful for implementing the copy-on-write optimization for the
-/// deep storage of value types:
+/// The `isKnownUniquelyReferenced(_:)` function is useful for implementating
+/// the copy-on-write optimization for the deep storage of value types:
 ///
 ///     mutating func modifyMe(_ arg: X) {
-///       if isKnownUniquelyReferenced(&myStorage) {
-///         myStorage.modifyInPlace(arg)
-///       }
-///       else {
-///         myStorage = self.createModified(myStorage, arg)
-///       }
+///         if isKnownUniquelyReferenced(&myStorage) {
+///             myStorage.modifyInPlace(arg)
+///         } else {
+///             myStorage = self.createModified(myStorage, arg)
+///         }
 ///     }
 ///
-/// This function is safe to use for `mutating` functions in
-/// multithreaded code because a false positive would imply that there
-/// is already a user-level data race on the value being mutated.
+/// Weak references do not affect the result of this function.
+///
+/// This function is safe to use for mutating functions in multithreaded code
+/// because a false positive implies that there is already a user-level data
+/// race on the value being mutated.
+///
+/// - Parameter object: An instance of a class. This function does *not* modify
+///   `object`; the use of `inout` is an implementation artifact.
+/// - Returns: `true` if `object` is a known to have a
+///   single strong reference; otherwise, `false`.
 public func isKnownUniquelyReferenced<T : AnyObject>(_ object: inout T) -> Bool
 {
   return _isUnique(&object)
@@ -481,28 +483,31 @@
   return _isUniqueOrPinned(&object)
 }
 
-/// Returns `true` iff `object` is known to be a class instance with a single
-/// strong reference.
+/// Returns a Boolean value indicating whether the given object is a
+/// class instance known to have a single strong reference.
 ///
-/// * Does *not* modify `object`; the use of `inout` is an
-///   implementation artifact.
-/// * Weak references do not affect the result of this function.
-///
-/// Useful for implementing the copy-on-write optimization for the
-/// deep storage of value types:
+/// The `isKnownUniquelyReferenced(_:)` function is useful for implementating
+/// the copy-on-write optimization for the deep storage of value types:
 ///
 ///     mutating func modifyMe(_ arg: X) {
-///       if isKnownUniquelyReferenced(&myStorage) {
-///         myStorage.modifyInPlace(arg)
-///       }
-///       else {
-///         myStorage = self.createModified(myStorage, arg)
-///       }
+///         if isKnownUniquelyReferenced(&myStorage) {
+///             myStorage.modifyInPlace(arg)
+///         } else {
+///             myStorage = self.createModified(myStorage, arg)
+///         }
 ///     }
 ///
-/// This function is safe to use for `mutating` functions in
-/// multithreaded code because a false positive would imply that there
-/// is already a user-level data race on the value being mutated.
+/// Weak references do not affect the result of this function.
+///
+/// This function is safe to use for mutating functions in multithreaded code
+/// because a false positive implies that there is already a user-level data
+/// race on the value being mutated.
+///
+/// - Parameter object: An instance of a class. This function does *not* modify
+///   `object`; the use of `inout` is an implementation artifact.
+/// - Returns: `true` if `object` is a known to have a
+///   single strong reference; otherwise, `false`. If `object` is `nil`, the
+///   return value is `false`.
 public func isKnownUniquelyReferenced<T : AnyObject>(
   _ object: inout T?
 ) -> Bool {
diff --git a/stdlib/public/core/Map.swift.gyb b/stdlib/public/core/Map.swift.gyb
index 33117cd..5f10ad9 100644
--- a/stdlib/public/core/Map.swift.gyb
+++ b/stdlib/public/core/Map.swift.gyb
@@ -65,7 +65,7 @@
     return _base.underestimatedCount
   }
 
-  /// Create an instance with elements `transform(x)` for each element
+  /// Creates an instance with elements `transform(x)` for each element
   /// `x` of base.
   internal init(_base: Base, transform: @escaping (Base.Iterator.Element) -> Element) {
     self._base = _base
@@ -114,7 +114,7 @@
   }
 %   end
 
-  /// Access the element at `position`.
+  /// Accesses the element at `position`.
   ///
   /// - Precondition: `position` is a valid position in `self` and
   ///   `position != endIndex`.
@@ -144,10 +144,10 @@
     return _base.indices
   }
 
-  /// Returns `true` iff `self` is empty.
+  /// A Boolean value indicating whether the collection is empty.
   public var isEmpty: Bool { return _base.isEmpty }
 
-  /// Returns the number of elements.
+  /// The number of elements in the collection.
   ///
   /// - Complexity: O(1) if `Index` conforms to `RandomAccessIndex`;
   ///   O(N) otherwise.
diff --git a/stdlib/public/core/MemoryLayout.swift b/stdlib/public/core/MemoryLayout.swift
index a3cb8af..a588c99 100644
--- a/stdlib/public/core/MemoryLayout.swift
+++ b/stdlib/public/core/MemoryLayout.swift
@@ -10,33 +10,32 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Accesses the memory layout of `T` through its
-/// `size`, `stride`, and `alignment` properties
+/// The memory layout of a type, describing its size, stride, and alignment.
 public enum MemoryLayout<T> {
 
-  /// Returns the contiguous memory footprint of `T`.
+  /// The contiguous memory footprint of the type.
   ///
-  /// Does not include any dynamically-allocated or "remote" 
-  /// storage. In particular, `MemoryLayout<T>.size`, when 
-  /// `T` is a class type, is the same regardless of how many 
-  /// stored properties `T` has.
+  /// The `size` property for a type `T` does not include any
+  /// dynamically-allocated or "remote" storage. In particular,
+  /// `MemoryLayout<T>.size`, when `T` is a class type, is the same regardless
+  /// of how many stored properties `T` has.
   @_transparent
   public static var size: Int {
     return Int(Builtin.sizeof(T.self))
   }
 
-  /// For instances of `T` in an `Array<T>`, returns the number of
-  /// bytes from the start of one instance to the start of the
-  /// next. This is the same as the number of bytes moved when an
-  /// `UnsafePointer<T>` is incremented. `T` may have a lower minimal
-  /// alignment that trades runtime performance for space
-  /// efficiency. The result is always positive.
+  /// The number of bytes from the start of one instance to the start of the
+  /// next, when stored in a contiguous array.
+  ///
+  /// This is the same as the number of bytes moved when an `UnsafePointer<T>`
+  /// is incremented. The type may have a lower minimal alignment that trades
+  /// runtime performance for space efficiency. The result is always positive.
   @_transparent
   public static var stride: Int {
     return Int(Builtin.strideof_nonzero(T.self))
   }
 
-  /// Returns the default memory alignment of `T`.
+  /// The default memory alignment of the type.
   @_transparent
   public static var alignment: Int {
     return Int(Builtin.alignof(T.self))
diff --git a/stdlib/public/core/Mirror.swift b/stdlib/public/core/Mirror.swift
index da9a99d..ddce305 100644
--- a/stdlib/public/core/Mirror.swift
+++ b/stdlib/public/core/Mirror.swift
@@ -385,7 +385,7 @@
 ///
 /// Do not declare new conformances to this protocol; they will not
 /// work as expected.
-// FIXME(ABI): this protocol should be “non-open” and you shouldn't be able to
+// FIXME(ABI): this protocol should be "non-open" and you shouldn't be able to
 // create conformances.
 public protocol MirrorPath {}
 extension IntMax : MirrorPath {}
@@ -596,7 +596,7 @@
 
 //===--- QuickLooks -------------------------------------------------------===//
 
-/// The sum of types that can be used as a quick look representation.
+/// The sum of types that can be used as a Quick Look representation.
 public enum PlaygroundQuickLook {
   /// Plain text.
   case text(String)
@@ -680,7 +680,7 @@
   /// - Note: If the dynamic type of `subject` has value semantics,
   ///   subsequent mutations of `subject` will not observable in
   ///   `Mirror`.  In general, though, the observability of such
-  /// mutations is unspecified.
+  ///   mutations is unspecified.
   public init(reflecting subject: Any) {
     if let customized = subject as? CustomPlaygroundQuickLookable {
       self = customized.customPlaygroundQuickLook
@@ -699,15 +699,15 @@
   }
 }
 
-/// A type that explicitly supplies its own PlaygroundQuickLook.
+/// A type that explicitly supplies its own playground Quick Look.
 ///
-/// Instances of any type can be `PlaygroundQuickLook(reflect:)`'ed
-/// upon, but if you are not satisfied with the `PlaygroundQuickLook`
-/// supplied for your type by default, you can make it conform to
-/// `CustomPlaygroundQuickLookable` and return a custom
-/// `PlaygroundQuickLook`.
+/// A Quick Look can be created for an instance of any type by using the
+/// `PlaygroundQuickLook(reflecting:)` initializer. If you are not satisfied
+/// with the representation supplied for your type by default, you can make it
+/// conform to the `CustomPlaygroundQuickLookable` protocol and provide a
+/// custom `PlaygroundQuickLook` instance.
 public protocol CustomPlaygroundQuickLookable {
-  /// A custom playground quick look for this instance.
+  /// A custom playground Quick Look for this instance.
   ///
   /// If this type has value semantics, the `PlaygroundQuickLook` instance
   /// should be unaffected by subsequent mutations.
diff --git a/stdlib/public/core/OptionSet.swift b/stdlib/public/core/OptionSet.swift
index cdfb9e5..b5c4aad 100644
--- a/stdlib/public/core/OptionSet.swift
+++ b/stdlib/public/core/OptionSet.swift
@@ -214,10 +214,12 @@
     return self.isSuperset(of: member)
   }
   
-  /// Inserts the given element into the option set if it is not already a
-  /// member.
+  /// Adds the given element to the option set if it is not already a member.
   ///
-  /// For example:
+  /// In the following example, the `.secondDay` shipping option is added to
+  /// the `freeOptions` option set if `purchasePrice` is greating than 50. For
+  /// the `ShippingOptions` declaration, see the `OptionSet` protocol
+  /// discussion.
   ///
   ///     let purchasePrice = 87.55
   ///
@@ -249,7 +251,10 @@
   
   /// Removes the given element and all elements subsumed by the given element.
   ///
-  /// For example:
+  /// In the following example, the `.priority` shipping option is removed from
+  /// the `options` option set. Attempting to remove the same shipping option
+  /// a second time results in `nil`, because `options` no longer contains
+  /// `.priority` as a member.
   ///
   ///     var options: ShippingOptions = [.secondDay, .priority]
   ///     let priorityOption = options.remove(.priority)
@@ -259,11 +264,11 @@
   ///     print(options.remove(.priority))
   ///     // Prints "nil"
   ///
-  /// In the following example, the `.express` element is passed to
-  /// `remove(_:)`. Although `.express` is not a member of `options`,
-  /// `.express` subsumes the remaining `.secondDay` element of the option
-  /// set. Therefore, `options` is emptied and the intersection between
-  /// `.express` and `options` is returned.
+  /// In the next example, the `.express` element is passed to `remove(_:)`.
+  /// Although `.express` is not a member of `options`, `.express` subsumes
+  /// the remaining `.secondDay` element of the option set. Therefore,
+  /// `options` is emptied and the intersection between `.express` and
+  /// `options` is returned.
   ///
   ///     let expressOption = options.remove(.express)
   ///     print(expressOption == .express)
diff --git a/stdlib/public/core/OutputStream.swift b/stdlib/public/core/OutputStream.swift
index 99be36b..f49c0a1 100644
--- a/stdlib/public/core/OutputStream.swift
+++ b/stdlib/public/core/OutputStream.swift
@@ -20,23 +20,24 @@
 ///
 /// You can send the output of the standard library's `print(_:to:)` and
 /// `dump(_:to:)` functions to an instance of a type that conforms to the
-/// `TextOutputStream` protocol instead of to standard output. Swift's `String`
-/// type conforms to `TextOutputStream` already, so you can capture the output
-/// from `print(_:to:)` and `dump(_:to:)` in a string instead of logging it to
-/// standard output.
+/// `TextOutputStream` protocol instead of to standard output. Swift's
+/// `String` type conforms to `TextOutputStream` already, so you can capture
+/// the output from `print(_:to:)` and `dump(_:to:)` in a string instead of
+/// logging it to standard output.
 ///
 ///     var s = ""
-///     for n in 1 ... 5 {
+///     for n in 1...5 {
 ///         print(n, terminator: "", to: &s)
 ///     }
 ///     // s == "12345"
 ///
 /// Conforming to the TextOutputStream Protocol
-/// =======================================
+/// ===========================================
 ///
-/// To make your custom type conform to the `TextOutputStream` protocol, implement
-/// the required `write(_:)` method. Functions that use an `TextOutputStream`
-/// target may call `write(_:)` multiple times per writing operation.
+/// To make your custom type conform to the `TextOutputStream` protocol,
+/// implement the required `write(_:)` method. Functions that use a
+/// `TextOutputStream` target may call `write(_:)` multiple times per writing
+/// operation.
 ///
 /// As an example, here's an implementation of an output stream that converts
 /// any input to its plain ASCII representation before sending it to standard
@@ -101,10 +102,11 @@
 ///
 /// Types that conform to the `CustomStringConvertible` protocol can provide
 /// their own representation to be used when converting an instance to a
-/// string. The `String(_:)` initializer is the preferred way to convert an
-/// instance of *any* type to a string. If the passed instance conforms to
-/// `CustomStringConvertible`, the `String(_:)` initializer and the
-/// `print(_:)` function use the instance's custom `description` property.
+/// string. The `String(describing:)` initializer is the preferred way to
+/// convert an instance of *any* type to a string. If the passed instance
+/// conforms to `CustomStringConvertible`, the `String(describing:)`
+/// initializer and the `print(_:)` function use the instance's custom
+/// `description` property.
 ///
 /// Accessing a type's `description` property directly or using
 /// `CustomStringConvertible` as a generic constraint is discouraged.
@@ -144,7 +146,8 @@
   /// A textual representation of this instance.
   ///
   /// Instead of accessing this property directly, convert an instance of any
-  /// type to a string by using the `String(_:)` initializer. For example:
+  /// type to a string by using the `String(describing:)` initializer. For
+  /// example:
   ///
   ///     struct Point: CustomStringConvertible {
   ///         let x: Int, y: Int
@@ -155,7 +158,7 @@
   ///     }
   ///
   ///     let p = Point(x: 21, y: 30)
-  ///     let s = String(p)
+  ///     let s = String(describing: p)
   ///     print(s)
   ///     // Prints "(21, 30)"
   ///
diff --git a/stdlib/public/core/Pointer.swift b/stdlib/public/core/Pointer.swift
index 44cabb1..c1e2ac0 100644
--- a/stdlib/public/core/Pointer.swift
+++ b/stdlib/public/core/Pointer.swift
@@ -17,7 +17,7 @@
   /// The underlying raw pointer value.
   var _rawValue: Builtin.RawPointer { get }
 
-  /// Construct a pointer from a raw value.
+  /// Creates a pointer from a raw value.
   init(_ _rawValue: Builtin.RawPointer)
 }
 
diff --git a/stdlib/public/core/Policy.swift b/stdlib/public/core/Policy.swift
index 1f99a49..78e5630 100644
--- a/stdlib/public/core/Policy.swift
+++ b/stdlib/public/core/Policy.swift
@@ -25,7 +25,6 @@
 ///     func crashAndBurn() -> Never {
 ///         fatalError("Something very, very bad happened")
 ///     }
-
 @_fixed_layout
 public enum Never {}
 
@@ -138,11 +137,11 @@
 /// that bridges to an Objective-C class. Many value types in Swift bridge to
 /// Objective-C counterparts, like `String` and `Int`.
 ///
-///     let s: AnyObject = "This is a bridged string."
+///     let s: AnyObject = "This is a bridged string." as NSString
 ///     print(s is NSString)
 ///     // Prints "true"
 ///
-///     let v: AnyObject = 100
+///     let v: AnyObject = 100 as NSNumber
 ///     print(type(of: v))
 ///     // Prints "__NSCFNumber"
 ///
@@ -158,34 +157,30 @@
 /// type and can be cast to that type using one of the type-cast operators
 /// (`as`, `as?`, or `as!`).
 ///
-/// In the code samples that follow, the elements of the `NSArray` instance
-/// `numberObjects` have `AnyObject` as their type. The first example uses the
-/// conditional downcast operator (`as?`) to conditionally cast the first
-/// object in the `numberObjects` array to an instance of Swift's `String`
-/// type.
+/// This example uses the conditional downcast operator (`as?`) to
+/// conditionally cast the `s` constant declared above to an instance of
+/// Swift's `String` type.
 ///
-///     let numberObjects: NSArray = ["one", "two", 3, 4]
-///
-///     let first: AnyObject = numberObjects[0]
-///     if let first = first as? String {
-///         print("The first object, '\(first)', is a String")
+///     if let message = s as? String {
+///         print("Succesful cast to String: \(message)")
 ///     }
-///     // Prints("The first object, 'one', is a String")
+///     // Prints "Succesful cast to String: This is a bridged string."
 ///
 /// If you have prior knowledge that an `AnyObject` instance has a particular
 /// type, you can use the unconditional downcast operator (`as!`). Performing
 /// an invalid cast triggers a runtime error.
 ///
-///     let second = numberObjects.object(at: 1) as! String
-///     print("'\(second)' is also a String")
-///     // Prints "'two' is also a String"
+///     let message = s as! String
+///     print("Succesful cast to String: \(message)")
+///     // Prints "Succesful cast to String: This is a bridged string."
 ///
-///     let badCase = numberObjects.object(at: 2) as! NSDate
+///     let badCase = v as! String
 ///     // Runtime error
 ///
 /// Casting is always safe in the context of a `switch` statement.
 ///
-///     for object in numberObjects {
+///     let mixedArray: [AnyObject] = [s, v]
+///     for object in mixedArray {
 ///         switch object {
 ///         case let x as String:
 ///             print("'\(x)' is a String")
@@ -193,25 +188,8 @@
 ///             print("'\(object)' is not a String")
 ///         }
 ///     }
-///     // Prints "'one' is a String"
-///     // Prints "'two' is a String"
-///     // Prints "'3' is not a String"
-///     // Prints "'4' is not a String"
-///
-/// You can call a method that takes an `AnyObject` parameter with an instance
-/// of any class, `@objc` protocol, or type that bridges to Objective-C. In
-/// the following example, the `toFind` constant is of type `Int`, which
-/// bridges to `NSNumber` when passed to an `NSArray` method that expects an
-/// `AnyObject` parameter:
-///
-///     let toFind = 3
-///     let i = numberObjects.index(of: toFind)
-///     if i != NSNotFound {
-///         print("Found '\(numberObjects[i])' at index \(i)")
-///     } else {
-///         print("Couldn't find \(toFind)")
-///     }
-///     // Prints "Found '3' at index 2"
+///     // Prints "'This is a bridged string.' is a String"
+///     // Prints "'100' is not a String"
 ///
 /// Accessing Objective-C Methods and Properties
 /// ============================================
@@ -225,7 +203,7 @@
 /// properties, respectively.
 ///
 /// This example defines an `IntegerRef` type with an `@objc` method named
-/// `getIntegerValue`.
+/// `getIntegerValue()`.
 ///
 ///     class IntegerRef {
 ///         let value: Int
@@ -242,35 +220,36 @@
 ///         return IntegerRef(100)
 ///     }
 ///
-///     let x: AnyObject = getObject()
+///     let obj: AnyObject = getObject()
 ///
-/// In the example, `x` has a static type of `AnyObject` and a dynamic type of
-/// `IntegerRef`. You can use optional chaining to call the `@objc` method
-/// `getIntegerValue()` on `x` safely. If you're sure of the dynamic type of
-/// `x`, you can call `getIntegerValue()` directly.
+/// In the example, `obj` has a static type of `AnyObject` and a dynamic type
+/// of `IntegerRef`. You can use optional chaining to call the `@objc` method
+/// `getIntegerValue()` on `obj` safely. If you're sure of the dynamic type of
+/// `obj`, you can call `getIntegerValue()` directly.
 ///
-///     let possibleValue = x.getIntegerValue?()
+///     let possibleValue = obj.getIntegerValue?()
 ///     print(possibleValue)
 ///     // Prints "Optional(100)"
 ///
-///     let certainValue = x.getIntegerValue()
+///     let certainValue = obj.getIntegerValue()
 ///     print(certainValue)
 ///     // Prints "100"
 ///
-/// If the dynamic type of `x` doesn't implement a `getIntegerValue()` method,
-/// the system returns a runtime error when you initialize `certainValue`.
+/// If the dynamic type of `obj` doesn't implement a `getIntegerValue()`
+/// method, the system returns a runtime error when you initialize
+/// `certainValue`.
 ///
-/// Alternatively, if you need to test whether `x.getValue()` exists, use
-/// optional binding before calling the method.
+/// Alternatively, if you need to test whether `obj.getIntegerValue()` exists,
+/// use optional binding before calling the method.
 ///
-///     if let f = x.getIntegerValue {
-///         print("The value of 'x' is \(f())")
+///     if let f = obj.getIntegerValue {
+///         print("The value of 'obj' is \(f())")
 ///     } else {
-///         print("'x' does not have a 'getIntegerValue()' method")
+///         print("'obj' does not have a 'getIntegerValue()' method")
 ///     }
-///     // Prints "The value of 'x' is 100"
+///     // Prints "The value of 'obj' is 100"
 ///
-/// - SeeAlso: `AnyClass`, `Any`
+/// - SeeAlso: `AnyClass`
 @objc
 public protocol AnyObject : class {}
 #else
@@ -316,7 +295,7 @@
 ///     print(getDefaultValue(NSString.self))
 ///     // Prints "nil"
 ///
-/// - SeeAlso: `AnyObject`, `Any`
+/// - SeeAlso: `AnyObject`
 public typealias AnyClass = AnyObject.Type
 
 /// A type that supports standard bitwise arithmetic operators.
diff --git a/stdlib/public/core/Print.swift b/stdlib/public/core/Print.swift
index 620ae84..d5cb76a 100644
--- a/stdlib/public/core/Print.swift
+++ b/stdlib/public/core/Print.swift
@@ -10,17 +10,48 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Writes the textual representations of `items`, separated by
-/// `separator` and terminated by `terminator`, into the standard
+/// Writes the textual representations of the given items into the standard
 /// output.
 ///
-/// The textual representations are obtained for each `item` via
-/// the expression `String(item)`.
+/// You can pass zero or more items to the `print(_:separator:terminator:)`
+/// function. The textual representation for each item is the same as that
+/// obtained by calling `String(item)`. The following example prints a string,
+/// a closed range of integers, and a group of floating-point values to
+/// standard output:
 ///
-/// - Note: To print without a trailing newline, pass `terminator: ""`
+///     print("One two three four five")
+///     // Prints "One two three four five"
 ///
-/// - SeeAlso: `debugPrint`, `Streamable`, `CustomStringConvertible`,
-///   `CustomDebugStringConvertible`
+///     print(1...5)
+///     // Prints "1...5"
+///
+///     print(1.0, 2.0, 3.0, 4.0, 5.0)
+///     // Prints "1.0 2.0 3.0 4.0 5.0"
+///
+/// To print the items separated by something other than a space, pass a string
+/// as `separator`.
+///
+///     print(1.0, 2.0, 3.0, 4.0, 5.0, separator: " ... ")
+///     // Prints "1.0 ... 2.0 ... 3.0 ... 4.0 ... 5.0"
+///
+/// The output from each call to `print(_:separator:terminator:)` includes a
+/// newline by default. To print the items without a trailing newline, pass an
+/// empty string as `terminator`.
+///
+///     for n in 1...5 {
+///         print(n, terminator: "")
+///     }
+///     // Prints "12345"
+///
+/// - Parameters:
+///   - items: Zero or more items to print.
+///   - separator: A string to print between each item. The default is a single
+///     space (`" "`).
+///   - terminator: The string to print after all items have been printed. The
+///     default is a newline (`"\n"`).
+///
+/// - SeeAlso: `debugPrint(_:separator:terminator:)`, `Streamable`,
+///   `CustomStringConvertible`, `CustomDebugStringConvertible`
 @inline(never)
 @_semantics("stdlib_binary_only")
 public func print(
@@ -41,17 +72,49 @@
   }
 }
 
-/// Writes the textual representations of `items` most suitable for
-/// debugging, separated by `separator` and terminated by
-/// `terminator`, into the standard output.
+/// Writes the textual representations of the given items most suitable for
+/// debugging into the standard output.
 ///
-/// The textual representations are obtained for each `item` via
-/// the expression `String(reflecting: item)`.
+/// You can pass zero or more items to the
+/// `debugPrint(_:separator:terminator:)` function. The textual representation
+/// for each item is the same as that obtained by calling
+/// `String(reflecting: item)`. The following example prints the debugging
+/// representation of a string, a closed range of integers, and a group of
+/// floating-point values to standard output:
 ///
-/// - Note: To print without a trailing newline, pass `terminator: ""`
+///     debugPrint("One two three four five")
+///     // Prints "One two three four five"
 ///
-/// - SeeAlso: `print`, `Streamable`, `CustomStringConvertible`,
-///   `CustomDebugStringConvertible`
+///     debugPrint(1...5)
+///     // Prints "CountableClosedRange(1...5)"
+///
+///     debugPrint(1.0, 2.0, 3.0, 4.0, 5.0)
+///     // Prints "1.0 2.0 3.0 4.0 5.0"
+///
+/// To print the items separated by something other than a space, pass a string
+/// as `separator`.
+///
+///     debugPrint(1.0, 2.0, 3.0, 4.0, 5.0, separator: " ... ")
+///     // Prints "1.0 ... 2.0 ... 3.0 ... 4.0 ... 5.0"
+///
+/// The output from each call to `debugPrint(_:separator:terminator:)` includes
+/// a newline by default. To print the items without a trailing newline, pass
+/// an empty string as `terminator`.
+///
+///     for n in 1...5 {
+///         debugPrint(n, terminator: "")
+///     }
+///     // Prints "12345"
+///
+/// - Parameters:
+///   - items: Zero or more items to print.
+///   - separator: A string to print between each item. The default is a single
+///     space (`" "`).
+///   - terminator: The string to print after all items have been printed. The
+///     default is a newline (`"\n"`).
+///
+/// - SeeAlso: `print(_:separator:terminator:)`, `Streamable`,
+///   `CustomStringConvertible`, `CustomDebugStringConvertible`
 @inline(never)
 @_semantics("stdlib_binary_only")
 public func debugPrint(
@@ -71,16 +134,47 @@
   }
 }
 
-/// Writes the textual representations of `items`, separated by
-/// `separator` and terminated by `terminator`, into `output`.
+/// Writes the textual representations of the given items into the given output
+/// stream.
 ///
-/// The textual representations are obtained for each `item` via
-/// the expression `String(item)`.
+/// You can pass zero or more items to the `print(_:separator:terminator:to:)`
+/// function. The textual representation for each item is the same as that
+/// obtained by calling `String(item)`. The following example prints a closed
+/// range of integers to a string:
 ///
-/// - Note: To print without a trailing newline, pass `terminator: ""`
+///     var range = "My range: "
+///     print(1...5, to: &range)
+///     // range == "My range: 1...5\n"
 ///
-/// - SeeAlso: `debugPrint`, `Streamable`, `CustomStringConvertible`,
-///   `CustomDebugStringConvertible`
+/// To print the items separated by something other than a space, pass a string
+/// as `separator`.
+///
+///     var separated = ""
+///     print(1.0, 2.0, 3.0, 4.0, 5.0, separator: " ... ", to: &separated)
+///     // separated == "1.0 ... 2.0 ... 3.0 ... 4.0 ... 5.0\n"
+///
+/// The output from each call to `print(_:separator:terminator:to:)` includes a
+/// newline by default. To print the items without a trailing newline, pass an
+/// empty string as `terminator`.
+///
+///     var numbers = ""
+///     for n in 1...5 {
+///         print(n, terminator: "", to: &numbers)
+///     }
+///     // numbers == "12345"
+///
+/// - Parameters:
+///   - items: Zero or more items to print.
+///   - separator: A string to print between each item. The default is a single
+///     space (`" "`).
+///   - terminator: The string to print after all items have been printed. The
+///     default is a newline (`"\n"`).
+///   - output: An output stream to receive the text representation of each
+///     item.
+///
+/// - SeeAlso: `print(_:separator:terminator:)`,
+///   `debugPrint(_:separator:terminator:to:)`, `TextOutputStream`,
+///   `Streamable`, `CustomStringConvertible`, `CustomDebugStringConvertible`
 @inline(__always)
 public func print<Target : TextOutputStream>(
   _ items: Any...,
@@ -91,17 +185,48 @@
   _print(items, separator: separator, terminator: terminator, to: &output)
 }
 
-/// Writes the textual representations of `items` most suitable for
-/// debugging, separated by `separator` and terminated by
-/// `terminator`, into `output`.
+/// Writes the textual representations of the given items most suitable for
+/// debugging into the given output stream.
 ///
-/// The textual representations are obtained for each `item` via
-/// the expression `String(reflecting: item)`.
+/// You can pass zero or more items to the
+/// `debugPrint(_:separator:terminator:to:)` function. The textual
+/// representation for each item is the same as that obtained by calling
+/// `String(reflecting: item)`. The following example prints a closed range of
+/// integers to a string:
 ///
-/// - Note: To print without a trailing newline, pass `terminator: ""`
+///     var range = "My range: "
+///     debugPrint(1...5, to: &range)
+///     // range == "My range: CountableClosedRange(1...5)\n"
 ///
-/// - SeeAlso: `print`, `Streamable`, `CustomStringConvertible`,
-///   `CustomDebugStringConvertible`
+/// To print the items separated by something other than a space, pass a string
+/// as `separator`.
+///
+///     var separated = ""
+///     debugPrint(1.0, 2.0, 3.0, 4.0, 5.0, separator: " ... ", to: &separated)
+///     // separated == "1.0 ... 2.0 ... 3.0 ... 4.0 ... 5.0\n"
+///
+/// The output from each call to `debugPrint(_:separator:terminator:to:)`
+/// includes a newline by default. To print the items without a trailing
+/// newline, pass an empty string as `terminator`.
+///
+///     var numbers = ""
+///     for n in 1...5 {
+///         debugPrint(n, terminator: "", to: &numbers)
+///     }
+///     // numbers == "12345"
+///
+/// - Parameters:
+///   - items: Zero or more items to print.
+///   - separator: A string to print between each item. The default is a single
+///     space (`" "`).
+///   - terminator: The string to print after all items have been printed. The
+///     default is a newline (`"\n"`).
+///   - output: An output stream to receive the text representation of each
+///     item.
+///
+/// - SeeAlso: `debugPrint(_:separator:terminator:)`,
+///   `print(_:separator:terminator:to:)`, `TextOutputStream`, `Streamable`,
+///   `CustomStringConvertible`, `CustomDebugStringConvertible`
 @inline(__always)
 public func debugPrint<Target : TextOutputStream>(
   _ items: Any...,
diff --git a/stdlib/public/core/RandomAccessCollection.swift b/stdlib/public/core/RandomAccessCollection.swift
index 8553822..609bbc2 100644
--- a/stdlib/public/core/RandomAccessCollection.swift
+++ b/stdlib/public/core/RandomAccessCollection.swift
@@ -125,9 +125,9 @@
   ///     print(j)
   ///     // Prints "nil"
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection, unless the index passed as
+  /// `limit` prevents offsetting beyond those bounds.
   ///
   /// - Parameters:
   ///   - i: A valid index of the array.
@@ -211,9 +211,8 @@
   ///     print(numbers[i])
   ///     // Prints "50"
   ///
-  /// Advancing an index beyond a collection's ending index or offsetting it
-  /// before a collection's starting index may trigger a runtime error. The
-  /// value passed as `n` must not result in such an operation.
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection.
   ///
   /// - Parameters:
   ///   - i: A valid index of the collection.
diff --git a/stdlib/public/core/Range.swift.gyb b/stdlib/public/core/Range.swift.gyb
index 3fd47fb..b7ff5f9 100644
--- a/stdlib/public/core/Range.swift.gyb
+++ b/stdlib/public/core/Range.swift.gyb
@@ -420,12 +420,28 @@
   /// Returns a Boolean value indicating whether this range and the given range
   /// contain an element in common.
   ///
-  /// For example:
+  /// This example shows two overlapping ranges:
   ///
   ///     let x: ${Self} = 0${op}20
   ///     print(x.overlaps(10${other_op}1000 as ${OtherSelf}))
   ///     // Prints "true"
   ///
+% if 'Closed' in Self:
+  /// Because a closed range includes its upper bound, the ranges in the
+  /// following example also overlap:
+  ///
+  ///     let y: ${OtherSelf} = 20${op}30
+  ///     print(x.overlaps(y))
+  ///     // Prints "true"
+% else:
+  /// Because a half-open range does not include its upper bound, the ranges
+  /// in the following example do not overlap:
+  ///
+  ///     let y: ${OtherSelf} = 20${op}30
+  ///     print(x.overlaps(y))
+  ///     // Prints "false"
+% end
+  ///
   /// - Parameter other: A range to check for elements in common.
   /// - Returns: `true` if this range and `other` have at least one element in
   ///   common; otherwise, `false`.
@@ -543,7 +559,9 @@
 /// Returns a half-open range that contains its lower bound but not its upper
 /// bound.
 ///
-/// For example:
+/// Use the half-open range operator (`..<`) to create a range of any type that
+/// conforms to the `Comparable` protocol. This example creates a
+/// `Range<Double>` from zero up to, but not including, 5.0.
 ///
 ///     let lessThanFive = 0.0..<5.0
 ///     print(lessThanFive.contains(3.14))  // Prints "true"
@@ -563,12 +581,21 @@
 /// Returns a countable half-open range that contains its lower bound but not
 /// its upper bound.
 ///
-/// For example:
+/// Use the half-open range operator (`..<`) to create a range of any type that
+/// conforms to the `Strideable` protocol with an associated integer `Stride`
+/// type, such as any of the standard library's integer types. This example
+/// creates a `CountableRange<Int>` from zero up to, but not including, 5.
 ///
 ///     let upToFive = 0..<5
 ///     print(upToFive.contains(3))         // Prints "true"
 ///     print(upToFive.contains(5))         // Prints "false"
 ///
+/// You can use sequence or collection methods on the `upToFive` countable
+/// range.
+///
+///     print(upToFive.count)               // Prints "5"
+///     print(upToFive.last)                // Prints "4"
+///
 /// - Parameters:
 ///   - minimum: The lower bound for the range.
 ///   - maximum: The upper bound for the range.
diff --git a/stdlib/public/core/RangeReplaceableCollection.swift.gyb b/stdlib/public/core/RangeReplaceableCollection.swift.gyb
index 42cc1d7..a5ac802 100644
--- a/stdlib/public/core/RangeReplaceableCollection.swift.gyb
+++ b/stdlib/public/core/RangeReplaceableCollection.swift.gyb
@@ -346,7 +346,9 @@
 
   /// Adds an element to the end of the collection.
   ///
-  /// For example:
+  /// If the collection does not have sufficient capacity for another element,
+  /// additional storage is allocated before appending `newElement`. The
+  /// following example adds a new number to an array of integers:
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
   ///     numbers.append(100)
@@ -372,9 +374,12 @@
 
   /// Adds the elements of a sequence to the end of the collection.
   ///
-  /// Use this method to append the elements of a sequence to the end of a
-  /// collection. This example appends the elements of a `Range<Int>` instance
-  /// to an array of integers.
+  /// Use this method to append the elements of a sequence or collection to the
+  /// end of this collection. The collection being appended to allocates any
+  /// additional necessary storage to hold the new elements.
+  ///
+  /// The following example appends the elements of a `Range<Int>` instance to
+  /// an array of integers:
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
   ///     numbers.append(contentsOf: 10...15)
@@ -383,7 +388,8 @@
   ///
   /// - Parameter newElements: The elements to append to the collection.
   ///
-  /// - Complexity: O(*n*), where *n* is the length of the resulting collection.
+  /// - Complexity: O(*n*), where *n* is the length of the resulting
+  ///   collection.
   mutating func append<S : Sequence>(contentsOf newElements: S)
     where S.Iterator.Element == Iterator.Element
 
@@ -565,7 +571,9 @@
 
   /// Adds an element to the end of the collection.
   ///
-  /// For example:
+  /// If the collection does not have sufficient capacity for another element,
+  /// additional storage is allocated before appending `newElement`. The
+  /// following example adds a new number to an array of integers:
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
   ///     numbers.append(100)
@@ -583,9 +591,12 @@
 
   /// Adds the elements of a sequence to the end of the collection.
   ///
-  /// Use this method to append the elements of a sequence to the end of a
-  /// collection. This example appends the elements of a `Range<Int>` instance
-  /// to an array of integers.
+  /// Use this method to append the elements of a sequence or collection to the
+  /// end of this collection. The collection being appended to allocates any
+  /// additional necessary storage to hold the new elements.
+  ///
+  /// The following example appends the elements of a `Range<Int>` instance to
+  /// an array of integers:
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
   ///     numbers.append(contentsOf: 10...15)
@@ -594,7 +605,8 @@
   ///
   /// - Parameter newElements: The elements to append to the collection.
   ///
-  /// - Complexity: O(*n*), where *n* is the length of the resulting collection.
+  /// - Complexity: O(*n*), where *n* is the length of the resulting
+  ///   collection.
   public mutating func append<S : Sequence>(contentsOf newElements: S)
     where S.Iterator.Element == Iterator.Element {
 
diff --git a/stdlib/public/core/Reflection.swift b/stdlib/public/core/Reflection.swift
index db55b97..ea78719 100644
--- a/stdlib/public/core/Reflection.swift
+++ b/stdlib/public/core/Reflection.swift
@@ -18,30 +18,59 @@
   internal let _value: Builtin.RawPointer
 
   // FIXME: Better hashing algorithm
-  /// The hash value.
+  /// The identifier's hash value.
   ///
-  /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
+  /// The hash value is not guaranteed to be stable across different
+  /// invocations of the same program.  Do not persist the hash value across
+  /// program runs.
   ///
-  /// - Note: The hash value is not guaranteed to be stable across
-  ///   different invocations of the same program.  Do not persist the
-  ///   hash value across program runs.
+  /// - SeeAlso: `Hashable`
   public var hashValue: Int {
     return Int(Builtin.ptrtoint_Word(_value))
   }
 
-  /// Construct an instance that uniquely identifies the class instance `x`.
+  /// Creates an instance that uniquely identifies the given class instance.
+  ///
+  /// The following example creates an example class `A` and compares instances
+  /// of the class using their object identifiers and the identical-to
+  /// operator (`===`):
+  ///
+  ///     class IntegerRef {
+  ///         let value: Int
+  ///         init(_ value: Int) {
+  ///             self.value = value
+  ///         }
+  ///     }
+  ///
+  ///     let x = IntegerRef(10)
+  ///     let y = x
+  ///
+  ///     print(ObjectIdentifier(x) == ObjectIdentifier(y))
+  ///     // Prints "true"
+  ///     print(x === y)
+  ///     // Prints "true"
+  ///
+  ///     let z = IntegerRef(10)
+  ///     print(ObjectIdentifier(x) == ObjectIdentifier(z))
+  ///     // Prints "false"
+  ///     print(x === z)
+  ///     // Prints "false"
+  ///
+  /// - Parameter x: An instance of a class.
   public init(_ x: AnyObject) {
     self._value = Builtin.bridgeToRawPointer(x)
   }
 
-  /// Construct an instance that uniquely identifies the metatype `x`.
+  /// Creates an instance that uniquely identifies the given metatype.
+  ///
+  /// - Parameter: A metatype.
   public init(_ x: Any.Type) {
     self._value = unsafeBitCast(x, to: Builtin.RawPointer.self)
   }
 }
 
 extension ObjectIdentifier : CustomDebugStringConvertible {
-  /// A textual representation of `self`, suitable for debugging.
+  /// A textual representation of the identifier, suitable for debugging.
   public var debugDescription: String {
     return "ObjectIdentifier(\(_rawPointerToString(_value)))"
   }
@@ -58,14 +87,16 @@
 }
 
 extension UInt {
-  /// Create a `UInt` that captures the full value of `objectID`.
+  /// Creates an integer that captures the full value of the given object
+  /// identifier.
   public init(bitPattern objectID: ObjectIdentifier) {
     self.init(Builtin.ptrtoint_Word(objectID._value))
   }
 }
 
 extension Int {
-  /// Create an `Int` that captures the full value of `objectID`.
+  /// Creates an integer that captures the full value of the given object
+  /// identifier.
   public init(bitPattern objectID: ObjectIdentifier) {
     self.init(bitPattern: UInt(bitPattern: objectID))
   }
@@ -140,7 +171,7 @@
 @_silgen_name("swift_reflectAny")
 internal func _reflect<T>(_ x: T) -> _Mirror
 
-/// Dump an object's contents using its mirror to the specified output stream.
+/// Dumps an object's contents using its mirror to the specified output stream.
 @discardableResult
 public func dump<T, TargetStream : TextOutputStream>(
   _ value: T,
@@ -165,7 +196,7 @@
   return value
 }
 
-/// Dump an object's contents using its mirror to standard output.
+/// Dumps an object's contents using its mirror to standard output.
 @discardableResult
 public func dump<T>(
   _ value: T,
diff --git a/stdlib/public/core/Repeat.swift b/stdlib/public/core/Repeat.swift
index e81c466..fdcadd8 100644
--- a/stdlib/public/core/Repeat.swift
+++ b/stdlib/public/core/Repeat.swift
@@ -10,18 +10,32 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A collection whose elements are all identical `Element`s.
+/// A collection whose elements are all identical.
+///
+/// You create an instance of the `Repeated` collection by calling the
+/// `repeatElement(_:count:)` function. The following example creates a
+/// collection containing the name "Humperdinck" repeated five times:
+///
+///     let repeatedName = repeatElement("Humperdinck", count: 5)
+///     for name in repeatedName {
+///         print(name)
+///     }
+///     // "Humperdinck"
+///     // "Humperdinck"
+///     // "Humperdinck"
+///     // "Humperdinck"
+///     // "Humperdinck"
 public struct Repeated<Element> : RandomAccessCollection {
 
   public typealias Indices = CountableRange<Int>
 
   /// A type that represents a valid position in the collection.
-  /// 
-  /// Valid indices consist of the position of every element and a
-  /// "past the end" position that's not valid for use as a subscript.
+  ///
+  /// Valid indices consist of the position of every element and a "past the
+  /// end" position that's not valid for use as a subscript.
   public typealias Index = Int
 
-  /// Construct an instance that contains `count` elements having the
+  /// Creates an instance that contains `count` elements having the
   /// value `repeatedValue`.
   internal init(_repeating repeatedValue: Element, count: Int) {
     _precondition(count >= 0, "Repetition count should be non-negative")
@@ -29,22 +43,28 @@
     self.repeatedValue = repeatedValue
   }
   
-  /// Always zero, which is the index of the first element in a
-  /// non-empty instance.
+  /// The position of the first element in a nonempty collection.
+  ///
+  /// In a `Repeated` collection, `startIndex` is always equal to zero. If the
+  /// collection is empty, `startIndex` is equal to `endIndex`.
   public var startIndex: Index {
     return 0
   }
 
-  /// Always equal to `count`, which is one greater than the index of
-  /// the last element in a non-empty instance.
+  /// The collection's "past the end" position---that is, the position one
+  /// greater than the last valid subscript argument.
+  ///
+  /// In a `Repeated` collection, `endIndex` is always equal to `count`. If the
+  /// collection is empty, `endIndex` is equal to `startIndex`.
   public var endIndex: Index {
     return count
   }
 
-  /// Access the element at `position`.
+  /// Accesses the element at the specified position.
   ///
-  /// - Precondition: `position` is a valid position in `self` and
-  ///   `position != endIndex`.
+  /// - Parameter position: The position of the element to access. `position`
+  ///   must be a valid index of the collection that is not equal to the
+  ///   `endIndex` property.
   public subscript(position: Int) -> Element {
     _precondition(position >= 0 && position < count, "Index out of range")
     return repeatedValue
@@ -57,7 +77,26 @@
   public let repeatedValue: Element
 }
 
-/// Return a collection containing `n` repetitions of `elementInstance`.
+/// Creates a collection containing the specified number of the given element.
+///
+/// The following example creates a `Repeated<Int>` collection containing five
+/// zeroes:
+///
+///     let zeroes = repeatElement(0, count: 5)
+///     for x in zeroes {
+///         print(x)
+///     }
+///     // 0
+///     // 0
+///     // 0
+///     // 0
+///     // 0
+///
+/// - Parameters:
+///   - element: The element to repeat.
+///   - count: The number of times to repeat `element`.
+/// - Returns: A collection that contains `count` elements that are all
+///   `element`.
 public func repeatElement<T>(_ element: T, count n: Int) -> Repeated<T> {
   return Repeated(_repeating: element, count: n)
 }
diff --git a/stdlib/public/core/Reverse.swift b/stdlib/public/core/Reverse.swift
index 8cb7978..2a396f7 100644
--- a/stdlib/public/core/Reverse.swift
+++ b/stdlib/public/core/Reverse.swift
@@ -13,6 +13,8 @@
 extension MutableCollection where Self : BidirectionalCollection {
   /// Reverses the elements of the collection in place.
   ///
+  /// The following example reverses the elements of an array of characters:
+  ///
   ///     var characters: [Character] = ["C", "a", "f", "é"]
   ///     characters.reverse()
   ///     print(cafe.characters)
@@ -65,7 +67,7 @@
   }
 }
 
-/// A Collection that presents the elements of its `Base` collection
+/// A collection that presents the elements of its base collection
 /// in reverse order.
 ///
 /// - Note: This type is the result of `x.reversed()` where `x` is a
@@ -176,7 +178,7 @@
   }
 }
 
-/// A Collection that presents the elements of its `Base` collection
+/// A collection that presents the elements of its base collection
 /// in reverse order.
 ///
 /// - Note: This type is the result of `x.reversed()` where `x` is a
@@ -326,7 +328,7 @@
   Self : BidirectionalCollection,
   Elements : BidirectionalCollection {
 
-  /// Returns the elements of `self` in reverse order.
+  /// Returns the elements of the collection in reverse order.
   ///
   /// - Complexity: O(1)
   public func reversed() -> LazyBidirectionalCollection<
@@ -341,7 +343,7 @@
   Self : RandomAccessCollection,
   Elements : RandomAccessCollection {
 
-  /// Returns the elements of `self` in reverse order.
+  /// Returns the elements of the collection in reverse order.
   ///
   /// - Complexity: O(1)
   public func reversed() -> LazyRandomAccessCollection<
diff --git a/stdlib/public/core/Sequence.swift b/stdlib/public/core/Sequence.swift
index 4074b2c..9444a18 100644
--- a/stdlib/public/core/Sequence.swift
+++ b/stdlib/public/core/Sequence.swift
@@ -60,8 +60,8 @@
 /// more idiomatic approach to traversing a sequence in Swift. Some
 /// algorithms, however, may call for direct iterator use.
 ///
-/// One example is the `reduce1(_:)` method. Similar to the `reduce(_:)` method
-/// defined in the standard library, which takes an initial value and a
+/// One example is the `reduce1(_:)` method. Similar to the `reduce(_:_:)`
+/// method defined in the standard library, which takes an initial value and a
 /// combining closure, `reduce1(_:)` uses the first element of the sequence as
 /// the initial value.
 ///
@@ -466,6 +466,7 @@
   ///
   /// - Parameter n: The number of elements to drop off the end of the
   ///   sequence. `n` must be greater than or equal to zero.
+  /// - Returns: A subsequence leaving off the specified number of elements.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the sequence.
   func dropLast(_ n: Int) -> SubSequence
@@ -1084,11 +1085,11 @@
     return AnySequence(_DropFirstSequence(_iterator: makeIterator(), limit: n))
   }
 
-  /// Returns a subsequence containing all but the given number of final 
+  /// Returns a subsequence containing all but the given number of final
   /// elements.
   ///
   /// The sequence must be finite. If the number of elements to drop exceeds
-  /// the number of elements in the sequence, the result is an empty 
+  /// the number of elements in the sequence, the result is an empty
   /// subsequence.
   ///
   ///     let numbers = [1, 2, 3, 4, 5]
@@ -1099,6 +1100,8 @@
   ///
   /// - Parameter n: The number of elements to drop off the end of the
   ///   sequence. `n` must be greater than or equal to zero.
+  /// - Returns: A subsequence leaving off the specified number of elements.
+  ///
   /// - Complexity: O(*n*), where *n* is the length of the sequence.
   public func dropLast(_ n: Int) -> AnySequence<Iterator.Element> {
     _precondition(n >= 0, "Can't drop a negative number of elements from a sequence")
@@ -1158,23 +1161,42 @@
   /// Returns a subsequence containing all but the first element of the
   /// sequence.
   ///
-  /// For example:
+  /// The following example drops the first element from an array of integers.
   ///
   ///     let numbers = [1, 2, 3, 4, 5]
   ///     print(numbers.dropFirst())
   ///     // Prints "[2, 3, 4, 5]"
   ///
+  /// If the sequence has no elements, the result is an empty subsequence.
+  ///
+  ///     let empty: [Int] = []
+  ///     print(empty.dropFirst())
+  ///     // Prints "[]"
+  ///
+  /// - Returns: A subsequence starting after the first element of the
+  ///   sequence.
+  ///
   /// - Complexity: O(1)
   public func dropFirst() -> SubSequence { return dropFirst(1) }
 
-  /// Returns a subsequence containing all but the last element of the sequence.
+  /// Returns a subsequence containing all but the last element of the
+  /// sequence.
   ///
-  /// The sequence must be finite.
+  /// The sequence must be finite. If the sequence has no elements, the result
+  /// is an empty subsequence.
   ///
   ///     let numbers = [1, 2, 3, 4, 5]
   ///     print(numbers.dropLast())
   ///     // Prints "[1, 2, 3, 4]"
   ///
+  /// If the sequence has no elements, the result is an empty subsequence.
+  ///
+  ///     let empty: [Int] = []
+  ///     print(empty.dropLast())
+  ///     // Prints "[]"
+  ///
+  /// - Returns: A subsequence leaving off the last element of the sequence.
+  ///
   /// - Complexity: O(*n*), where *n* is the length of the sequence.
   public func dropLast() -> SubSequence  { return dropLast(1) }
 }
@@ -1204,7 +1226,7 @@
 public struct IteratorSequence<
   Base : IteratorProtocol
 > : IteratorProtocol, Sequence {
-  /// Construct an instance whose iterator is a copy of `base`.
+  /// Creates an instance whose iterator is a copy of `base`.
   public init(_ base: Base) {
     _base = base
   }
diff --git a/stdlib/public/core/SequenceAlgorithms.swift.gyb b/stdlib/public/core/SequenceAlgorithms.swift.gyb
index 353e27e..2e8843b 100644
--- a/stdlib/public/core/SequenceAlgorithms.swift.gyb
+++ b/stdlib/public/core/SequenceAlgorithms.swift.gyb
@@ -56,7 +56,7 @@
   /// This example enumerates the characters of the string "Swift" and prints
   /// each character along with its place in the string.
   ///
-  ///     > for (n, c) in "Swift".characters.enumerated() {
+  ///     for (n, c) in "Swift".characters.enumerated() {
   ///         print("\(n): '\(c)'")
   ///     }
   ///     // Prints "0: 'S'"
@@ -65,6 +65,35 @@
   ///     // Prints "3: 'f'"
   ///     // Prints "4: 't'"
   ///
+  /// When enumerating a collection, the integer part of each pair is a counter
+  /// for the enumeration, not necessarily the index of the paired value.
+  /// These counters can only be used as indices in instances of zero-based,
+  /// integer-indexed collections, such as `Array` and `ContiguousArray`. For
+  /// other collections the counters may be out of range or of the wrong type
+  /// to use as an index. To iterate over the elements of collection with its
+  /// indices, use the `zip(_:_:)` function.
+  ///
+  /// This example iterates over the indices and elements of a set, building a
+  /// list of indices of names with five or fewer letters.
+  ///
+  ///     let names: Set = ["Sofia", "Camilla", "Martina", "Mateo", "Nicolás"]
+  ///     var shorterIndices: [SetIndex<String>] = []
+  ///     for (i, name) in zip(names.indices, names) {
+  ///         if name.characters.count <= 5 {
+  ///             shorterIndices.append(i)
+  ///         }
+  ///     }
+  ///
+  /// Now that the `shorterIndices` array holds the indices of the shorter
+  /// names in the `names` set, you can use those indices to access elements in
+  /// the set.
+  ///
+  ///     for i in shorterIndices {
+  ///         print(names[i])
+  ///     }
+  ///     // Prints "Sofia"
+  ///     // Prints "Mateo"
+  ///
   /// - Returns: A sequence of pairs enumerating the sequence.
   public func enumerated() -> EnumeratedSequence<Self> {
     return EnumeratedSequence(_base: self)
@@ -214,28 +243,33 @@
   ///   - areEquivalent: A predicate that returns `true` if its two arguments
   ///     are equivalent; otherwise, `false`.
   /// - Returns: `true` if the initial elements of the sequence are equivalent
-  ///   to the elements of `possiblePrefix`; otherwise, `false`. Returns
-  ///   `true` if `possiblePrefix` has no elements.
+  ///   to the elements of `possiblePrefix`; otherwise, `false`. If
+  ///   `possiblePrefix` has no elements, the return value is `true`.
   ///
   /// - SeeAlso: `starts(with:)`
 %   else:
   /// Returns a Boolean value indicating whether the initial elements of the
   /// sequence are the same as the elements in another sequence.
   ///
-  /// For example:
+  /// This example tests whether one countable range begins with the elements
+  /// of another countable range.
   ///
   ///     let a = 1...3
   ///     let b = 1...10
   ///
   ///     print(b.starts(with: a))
   ///     // Prints "true"
+  ///
+  /// Passing a sequence with no elements or an empty collection as
+  /// `possiblePrefix` always results in `true`.
+  ///
   ///     print(b.starts(with: []))
   ///     // Prints "true"
   ///
   /// - Parameter possiblePrefix: A sequence to compare to this sequence.
   /// - Returns: `true` if the initial elements of the sequence are the same as
-  ///   the elements of `possiblePrefix`; otherwise, `false`. Returns `true`
-  ///   if `possiblePrefix` has no elements.
+  ///   the elements of `possiblePrefix`; otherwise, `false`. If
+  ///   `possiblePrefix` has no elements, the return value is `true`.
   ///
   /// - SeeAlso: `starts(with:by:)`
 %   end
@@ -299,7 +333,8 @@
   ///
   /// At least one of the sequences must be finite.
   ///
-  /// For example:
+  /// This example tests whether one countable range shares the same elements
+  /// as another countable range and as an array with the same elements.
   ///
   ///     let a = 1...3
   ///     let b = 1...10
@@ -380,7 +415,8 @@
   /// sequence in a lexicographical ("dictionary") ordering, using the
   /// less-than operator (`<`) to compare elements.
   ///
-  /// For example:
+  /// This example uses the `lexicographicallyPrecedes` method to test which
+  /// array of integers comes first in a lexicographical ordering.
   ///
   ///     let a = [1, 2, 2, 2]
   ///     let b = [1, 2, 3, 4]
@@ -551,7 +587,7 @@
   ///     value and an element of the sequence into a new accumulating
   ///     value, to be used in the next call of the
   ///     `nextPartialResult` closure or returned to the caller.
-    /// - Returns: The final accumulated value.
+  /// - Returns: The final accumulated value.
   public func reduce<Result>(
     _ initialResult: Result,
     _ nextPartialResult:
diff --git a/stdlib/public/core/SetAlgebra.swift b/stdlib/public/core/SetAlgebra.swift
index 92405bf..9de5a5a 100644
--- a/stdlib/public/core/SetAlgebra.swift
+++ b/stdlib/public/core/SetAlgebra.swift
@@ -75,10 +75,11 @@
   
   /// Returns a Boolean value that indicates whether the given element exists
   /// in the set.
-  /// 
-  /// For example:
   ///
-  ///     let primes: Set = [2, 3, 5, 7]
+  /// This example uses the `contains(_:)` method to test whether an integer is
+  /// a member of a set of prime numbers.
+  ///
+  ///     let primes: Set = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37]
   ///     let x = 5
   ///     if primes.contains(x) {
   ///         print("\(x) is prime!")
@@ -93,7 +94,8 @@
 
   /// Returns a new set with the elements of both this and the given set.
   ///
-  /// For example:
+  /// In the following example, the `attendeesAndVisitors` set is made up
+  /// of the elements of the `attendees` and `visitors` sets:
   ///
   ///     let attendees: Set = ["Alicia", "Bethany", "Diana"]
   ///     let visitors = ["Marcia", "Nathaniel"]
@@ -102,7 +104,7 @@
   ///     // Prints "["Diana", "Nathaniel", "Bethany", "Alicia", "Marcia"]"
   ///
   /// If the set already contains one or more elements that are also in
-  /// `other`, the existing members are kept. For example:
+  /// `other`, the existing members are kept.
   ///
   ///     let initialIndices = Set(0..<5)
   ///     let expandedIndices = initialIndices.union([2, 3, 6, 7])
@@ -120,7 +122,10 @@
   /// Returns a new set with the elements that are common to both this set and
   /// the given set.
   ///
-  /// For example:
+  /// In the following example, the `bothNeighborsAndEmployees` set is made up
+  /// of the elements that are in *both* the `employees` and `neighbors` sets.
+  /// Elements that are only in one or the other are left out of the result of
+  /// the intersection.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -139,7 +144,10 @@
   /// Returns a new set with the elements that are either in this set or in the
   /// given set, but not in both.
   ///
-  /// For example:
+  /// In the following example, the `eitherNeighborsOrEmployees` set is made up
+  /// of the elements of the `employees` and `neighbors` sets that are not in
+  /// both `employees` *and* `neighbors`. In particular, the names `"Bethany"`
+  /// and `"Eric"` do not appear in `eitherNeighborsOrEmployees`.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani"]
@@ -229,7 +237,8 @@
   
   /// Adds the elements of the given set to the set.
   ///
-  /// For example:
+  /// In the following example, the elements of the `visitors` set are added to
+  /// the `attendees` set:
   ///
   ///     var attendees: Set = ["Alicia", "Bethany", "Diana"]
   ///     let visitors: Set = ["Marcia", "Nathaniel"]
@@ -238,7 +247,7 @@
   ///     // Prints "["Diana", "Nathaniel", "Bethany", "Alicia", "Marcia"]"
   ///
   /// If the set already contains one or more elements that are also in
-  /// `other`, the existing members are kept. For example:
+  /// `other`, the existing members are kept.
   ///
   ///     var initialIndices = Set(0..<5)
   ///     initialIndices.formUnion([2, 3, 6, 7])
@@ -250,7 +259,9 @@
 
   /// Removes the elements of this set that aren't also in the given set.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// not also members of the `neighbors` set are removed. In particular, the
+  /// names `"Alicia"`, `"Chris"`, and `"Diana"` are removed.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -261,16 +272,21 @@
   /// - Parameter other: A set of the same type as the current set.
   mutating func formIntersection(_ other: Self)
 
-  /// Removes the elements of the set that are also in the given set and
-  /// adds the members of the given set that are not already in the set.
+  /// Removes the elements of the set that are also in the given set and adds
+  /// the members of the given set that are not already in the set.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// also members of `neighbors` are removed from `employees`, while the
+  /// elements of `neighbors` that are not members of `employees` are added to
+  /// `employees`. In particular, the names `"Alicia"`, `"Chris"`, and
+  /// `"Diana"` are removed from `employees` while the names `"Forlani"` and
+  /// `"Greta"` are added.
   ///
-  ///     var employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
-  ///     let neighbors: Set = ["Bethany", "Eric", "Forlani"]
+  ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
+  ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
   ///     employees.formSymmetricDifference(neighbors)
   ///     print(employees)
-  ///     // Prints "["Diana", "Forlani", "Alicia"]"
+  ///     // Prints "["Diana", "Chris", "Forlani", "Alicia", "Greta"]"
   ///
   /// - Parameter other: A set of the same type.
   mutating func formSymmetricDifference(_ other: Self)
@@ -279,7 +295,8 @@
   /// Returns a new set containing the elements of this set that do not occur
   /// in the given set.
   ///
-  /// For example:
+  /// In the following example, the `nonNeighbors` set is made up of the
+  /// elements of the `employees` set that are not elements of `neighbors`:
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -309,7 +326,8 @@
   /// Returns a Boolean value that indicates whether the set has no members in
   /// common with the given set.
   ///
-  /// For example:
+  /// In the following example, the `employees` set is disjoint with the
+  /// `visitors` set because no name appears in both sets.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let visitors: Set = ["Marcia", "Nathaniel", "Olivia"]
@@ -354,7 +372,9 @@
 
   /// Removes the elements of the given set from this set.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// also members of the `neighbors` set are removed. In particular, the
+  /// names `"Bethany"` and `"Eric"` are removed from `employees`.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -413,7 +433,9 @@
 
   /// Removes the elements of the given set from this set.
   ///
-  /// For example:
+  /// In the following example, the elements of the `employees` set that are
+  /// also members of the `neighbors` set are removed. In particular, the
+  /// names `"Bethany"` and `"Eric"` are removed from `employees`.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -464,7 +486,8 @@
   /// Returns a Boolean value that indicates whether the set has no members in
   /// common with the given set.
   ///
-  /// For example:
+  /// In the following example, the `employees` set is disjoint with the
+  /// `visitors` set because no name appears in both sets.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let visitors: Set = ["Marcia", "Nathaniel", "Olivia"]
@@ -481,7 +504,8 @@
   /// Returns a new set containing the elements of this set that do not occur
   /// in the given set.
   ///
-  /// For example:
+  /// In the following example, the `nonNeighbors` set is made up of the
+  /// elements of the `employees` set that are not elements of `neighbors`:
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -511,6 +535,8 @@
   ///     let attendees: Set = ["Alicia", "Bethany", "Diana"]
   ///     print(employees.isStrictSuperset(of: attendees))
   ///     // Prints "true"
+  ///
+  ///     // A set is never a strict superset of itself:
   ///     print(employees.isStrictSuperset(of: employees))
   ///     // Prints "false"
   ///
diff --git a/stdlib/public/core/Slice.swift.gyb b/stdlib/public/core/Slice.swift.gyb
index 571b5c8..2f52815 100644
--- a/stdlib/public/core/Slice.swift.gyb
+++ b/stdlib/public/core/Slice.swift.gyb
@@ -421,6 +421,10 @@
   ///     print(Array(subSequence))
   ///     // Prints "[5, 6, 7, 8, 9]"
   ///
+  /// In this example, the expression `singleDigits.dropFirst(5))` is
+  /// equivalent to calling this initializer with with `singleDigits` and a
+  /// range covering the last five items of `singleDigits.indices`.
+  ///
   /// - Parameters:
   ///   - base: The collection to create a view into.
   ///   - bounds: The range of indices to allow access to in the new slice.
@@ -437,6 +441,23 @@
 %     end
 
   /// The underlying collection of the slice.
+  ///
+  /// You can use a slice's `base` property to access its base collection. The
+  /// following example declares `singleDigits`, a range of single digit
+  /// integers, and then drops the first element to create a slice of that
+  /// range, `singleNonZeroDigits`. The `base` property of the slice is equal
+  /// to `singleDigits`.
+  ///
+  ///     let singleDigits = 0..<10
+  ///     let singleNonZeroDigits = singleDigits.dropFirst()
+  ///     // singleNonZeroDigits is a RandomAccessSlice<CountableRange<Int>>
+  ///
+  ///     print(singleNonZeroDigits.count)
+  ///     // Prints "9"
+  ///     prints(singleNonZeroDigits.base.count)
+  ///     // Prints "10"
+  ///     print(singleDigits == singleNonZeroDigits.base)
+  ///     // Prints "true"
   public var base: Base {
     return _base
   }
diff --git a/stdlib/public/core/SliceBuffer.swift b/stdlib/public/core/SliceBuffer.swift
index cf66905..8e96bc1 100644
--- a/stdlib/public/core/SliceBuffer.swift
+++ b/stdlib/public/core/SliceBuffer.swift
@@ -37,7 +37,7 @@
     _invariantCheck()
   }
 
-  public init(_ buffer: NativeBuffer, shiftedToStartIndex: Int) {
+  public init(_buffer buffer: NativeBuffer, shiftedToStartIndex: Int) {
     let shift = buffer.startIndex - shiftedToStartIndex
     self.init(
       owner: buffer.owner,
diff --git a/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb b/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
index c62fb0b..2667d72 100644
--- a/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
+++ b/stdlib/public/core/StringRangeReplaceableCollection.swift.gyb
@@ -35,7 +35,11 @@
   /// In an empty string, `endIndex` is equal to `startIndex`.
   public var endIndex: Index { return characters.endIndex }
 
-    // TODO: swift-3-indexing-model - add docs
+  /// Returns the position immediately after the given index.
+  ///
+  /// - Parameter i: A valid index of the collection. `i` must be less than
+  ///   `endIndex`.
+  /// - Returns: The index value immediately after `i`.
   public func index(after i: Index) -> Index {
     return characters.index(after: i)
   }
@@ -45,19 +49,86 @@
     return characters.index(before: i)
   }
 
-  // TODO: swift-3-indexing-model - add docs
+  /// Returns an index that is the specified distance from the given index.
+  ///
+  /// The following example obtains an index advanced four positions from a
+  /// string's starting index and then prints the character at that position.
+  ///
+  ///     let s = "Swift"
+  ///     let i = s.index(s.startIndex, offsetBy: 4)
+  ///     print(s[i])
+  ///     // Prints "t"
+  ///
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection.
+  ///
+  /// - Parameters:
+  ///   - i: A valid index of the collection.
+  ///   - n: The distance to offset `i`.
+  /// - Returns: An index offset by `n` from the index `i`. If `n` is positive,
+  ///   this is the same value as the result of `n` calls to `index(after:)`.
+  ///   If `n` is negative, this is the same value as the result of `-n` calls
+  ///   to `index(before:)`.
+  ///
+  /// - SeeAlso: `index(_:offsetBy:limitedBy:)`
+  /// - Complexity: O(*n*), where *n* is the absolute value of `n`.
   public func index(_ i: Index, offsetBy n: IndexDistance) -> Index {
     return characters.index(i, offsetBy: n)
   }
 
-  // TODO: swift-3-indexing-model - add docs
+  /// Returns an index that is the specified distance from the given index,
+  /// unless that distance is beyond a given limiting index.
+  ///
+  /// The following example obtains an index advanced four positions from a
+  /// string's starting index and then prints the character at that position.
+  /// The operation doesn't require going beyond the limiting `s.endIndex`
+  /// value, so it succeeds.
+  ///
+  ///     let s = "Swift"
+  ///     if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
+  ///         print(s[i])
+  ///     }
+  ///     // Prints "t"
+  ///
+  /// The next example attempts to retrieve an index six positions from
+  /// `s.startIndex` but fails, because that distance is beyond the index
+  /// passed as `limit`.
+  ///
+  ///     let j = s.index(s.startIndex, offsetBy: 6, limitedBy: s.endIndex)
+  ///     print(j)
+  ///     // Prints "nil"
+  ///
+  /// The value passed as `n` must not offset `i` beyond the `endIndex` or
+  /// before the `startIndex` of this collection, unless the index passed as
+  /// `limit` prevents offsetting beyond those bounds.
+  ///
+  /// - Parameters:
+  ///   - i: A valid index of the collection.
+  ///   - n: The distance to offset `i`.
+  ///   - limit: A valid index of the collection to use as a limit. If `n > 0`,
+  ///     a limit that is less than `i` has no effect. Likewise, if `n < 0`, a
+  ///     limit that is greater than `i` has no effect.
+  /// - Returns: An index offset by `n` from the index `i`, unless that index
+  ///   would be beyond `limit` in the direction of movement. In that case,
+  ///   the method returns `nil`.
+  ///
+  /// - SeeAlso: `index(_:offsetBy:)`
+  /// - Complexity: O(*n*), where *n* is the absolute value of `n`.
   public func index(
     _ i: Index, offsetBy n: IndexDistance, limitedBy limit: Index
   ) -> Index? {
     return characters.index(i, offsetBy: n, limitedBy: limit)
   }
 
-  // TODO: swift-3-indexing-model - add docs
+  /// Returns the distance between two indices.
+  ///
+  /// - Parameters:
+  ///   - start: A valid index of the collection.
+  ///   - end: Another valid index of the collection. If `end` is equal to
+  ///     `start`, the result is zero.
+  /// - Returns: The distance between `start` and `end`.
+  ///
+  /// - Complexity: O(*n*), where *n* is the resulting distance.
   public func distance(from start: Index, to end: Index) -> IndexDistance {
     return characters.distance(from: start, to: end)
   }
diff --git a/stdlib/public/core/Tuple.swift.gyb b/stdlib/public/core/Tuple.swift.gyb
index 9740aee..e3d6d7f 100644
--- a/stdlib/public/core/Tuple.swift.gyb
+++ b/stdlib/public/core/Tuple.swift.gyb
@@ -12,14 +12,44 @@
 
 // Generate comparison functions for tuples up to some reasonable arity.
 
+%{
+
+comparableOperators = [
+  ('<', 'before'),
+  ('<=', 'before or the same as'),
+  ('>', 'after'),
+  ('>=', 'after or the same as')
+]
+
+}%
+
 % for arity in range(2,7):
 %   typeParams = [chr(ord("A") + i) for i in range(arity)]
 %   tupleT = "({})".format(",".join(typeParams))
-
 %   equatableTypeParams = ", ".join(["{} : Equatable".format(c) for c in typeParams])
 
-/// Returns `true` iff each component of `lhs` is equal to the corresponding
-/// component of `rhs`.
+%   originalTuple = "(\"a\", {})".format(", ".join(map(str, range(1, arity))))
+%   greaterTuple = "(\"a\", {})".format(", ".join(map(str, range(1, arity - 1) + [arity])))
+
+/// Returns a Boolean value indicating whether the corresponding components of
+/// two tuples are equal.
+///
+/// For two tuples to compare as equal, each corresponding pair of components
+/// must be equal. The following example compares tuples made up of ${arity}
+/// components:
+///
+///     let a = ${originalTuple}
+///     let b = ${originalTuple}
+///     print(a == b)
+///     // Prints "true"
+///
+///     let c = ${greaterTuple}
+///     print(a == c)
+///     // Prints "false"
+///
+/// - Parameters:
+///   - lhs: A tuple of `Equatable` elements.
+///   - rhs: Another tuple of elements of the same type as `lhs`.
 public func == <${equatableTypeParams}>(lhs: ${tupleT}, rhs: ${tupleT}) -> Bool {
   guard lhs.0 == rhs.0 else { return false }
   /*tail*/ return (
@@ -29,8 +59,25 @@
   )
 }
 
-/// Returns `true` iff any component of `lhs` is not equal to the corresponding
-/// component of `rhs`.
+/// Returns a Boolean value indicating whether any corresponding components of
+/// the two tuples are not equal.
+///
+/// For two tuples to compare as equal, each corresponding pair of components
+/// must be equal. The following example compares tuples made up of ${arity}
+/// components:
+///
+///     let a = ${originalTuple}
+///     let b = ${originalTuple}
+///     print(a != b)
+///     // Prints "false"
+///
+///     let c = ${greaterTuple}
+///     print(a != c)
+///     // Prints "true"
+///
+/// - Parameters:
+///   - lhs: A tuple of `Equatable` elements.
+///   - rhs: Another tuple of elements of the same type as `lhs`.
 public func != <${equatableTypeParams}>(lhs: ${tupleT}, rhs: ${tupleT}) -> Bool {
   guard lhs.0 == rhs.0 else { return true }
   /*tail*/ return (
@@ -41,22 +88,25 @@
 }
 
 %   comparableTypeParams = ", ".join(["{} : Comparable".format(c) for c in typeParams])
-%   for op in ["<", ">"]:
-%     for opeq in ["", "="]:
-/// A [lexicographical order](https://en.wikipedia.org/wiki/Lexicographical_order)
-/// over tuples of `Comparable` elements.
+%   for op, phrase in comparableOperators:
+/// Returns a Boolean value indicating whether the first tuple is ordered
+/// ${phrase} the second in a lexicographical ordering.
 ///
-/// Given two tuples `(a1, a2, ..., aN)` and `(b1, b2, ..., bN)`, the
-/// first tuple is `${op}${opeq}` the second tuple iff `a1 ${op} b1` or
-/// (`a1 == b1` and `(a2, ..., aN) ${op}${opeq} (b2, ..., bN)`).
-public func ${op}${opeq} <${comparableTypeParams}>(lhs: ${tupleT}, rhs: ${tupleT}) -> Bool {
-  if lhs.0 != rhs.0 { return lhs.0 ${op}${opeq} rhs.0 }
+/// Given two tuples `(a1, a2, ..., aN)` and `(b1, b2, ..., bN)`, the first
+/// tuple is ${phrase} the second tuple if and only if
+/// `a1 ${op.replace('=', '')} b1` or (`a1 == b1` and
+/// `(a2, ..., aN) ${op} (b2, ..., bN)`).
+///
+/// - Parameters:
+///   - lhs: A tuple of `Comparable` elements.
+///   - rhs: Another tuple of elements of the same type as `lhs`.
+public func ${op} <${comparableTypeParams}>(lhs: ${tupleT}, rhs: ${tupleT}) -> Bool {
+  if lhs.0 != rhs.0 { return lhs.0 ${op} rhs.0 }
   /*tail*/ return (
     ${", ".join("lhs.{}".format(i) for i in range(1, arity))}
-  ) ${op}${opeq} (
+  ) ${op} (
     ${", ".join("rhs.{}".format(i) for i in range(1, arity))}
   )
 }
-%     end
 %   end
 % end
diff --git a/stdlib/public/core/UnicodeScalar.swift b/stdlib/public/core/UnicodeScalar.swift
index 822b626..9c7439b 100644
--- a/stdlib/public/core/UnicodeScalar.swift
+++ b/stdlib/public/core/UnicodeScalar.swift
@@ -404,10 +404,11 @@
     return 0 + UTF16.width(value)
   }
 
-  /// Access the code unit at `position`.
+  /// Accesses the code unit at the specified position.
   ///
-  /// - Precondition: `position` is a valid position in `self` and
-  ///   `position != endIndex`.
+  /// - Parameter position: The position of the element to access. `position`
+  ///   must be a valid index of the collection that is not equal to the
+  ///   `endIndex` property.
   subscript(position: Int) -> UTF16.CodeUnit {
     return position == 0 ? (
       endIndex == 1 ? UTF16.CodeUnit(value.value) : UTF16.leadSurrogate(value)
diff --git a/stdlib/public/core/Unmanaged.swift b/stdlib/public/core/Unmanaged.swift
index e2b2988..23e6a39 100644
--- a/stdlib/public/core/Unmanaged.swift
+++ b/stdlib/public/core/Unmanaged.swift
@@ -22,41 +22,50 @@
   @_transparent
   internal init(_private: Instance) { _value = _private }
 
-  /// Unsafely turn an opaque C pointer into an unmanaged
-  /// class reference.
+  /// Unsafely turns an opaque C pointer into an unmanaged class reference.
   ///
   /// This operation does not change reference counts.
   ///
   ///     let str: CFString = Unmanaged.fromOpaque(ptr).takeUnretainedValue()
+  ///
+  /// - Parameter value: An opaque C pointer.
+  /// - Returns: An unmanaged class reference to `value`.
   @_transparent
   public static func fromOpaque(_ value: UnsafeRawPointer) -> Unmanaged {
     return Unmanaged(_private: unsafeBitCast(value, to: Instance.self))
   }
 
-  /// Unsafely convert an unmanaged class reference to a pointer
+  /// Unsafely converts an unmanaged class reference to a pointer.
   ///
   /// This operation does not change reference counts.
   ///
   ///     let str0: CFString = "boxcar"
   ///     let bits = Unmanaged.passUnretained(str0)
   ///     let ptr = bits.toOpaque()
+  ///
+  /// - Returns: An opaque pointer to the value of this unmanaged reference.
   @_transparent
   public func toOpaque() -> UnsafeMutableRawPointer {
     return unsafeBitCast(_value, to: UnsafeMutableRawPointer.self)
   }
 
-  /// Create an unmanaged reference with an unbalanced retain.
-  /// The object will leak if nothing eventually balances the retain.
+  /// Creates an unmanaged reference with an unbalanced retain.
   ///
-  /// This is useful when passing an object to an API which Swift
-  /// does not know the ownership rules for, but you know that the
-  /// API expects you to pass the object at +1.
+  /// The instance passed as `value` will leak if nothing eventually balances
+  /// the retain.
+  ///
+  /// This is useful when passing an object to an API which Swift does not know
+  /// the ownership rules for, but you know that the API expects you to pass
+  /// the object at +1.
+  ///
+  /// - Parameter value: A class instance.
+  /// - Returns: An unmanaged reference to the object passed as `value`.
   @_transparent
   public static func passRetained(_ value: Instance) -> Unmanaged {
     return Unmanaged(_private: value).retain()
   }
 
-  /// Create an unmanaged reference without performing an unbalanced
+  /// Creates an unmanaged reference without performing an unbalanced
   /// retain.
   ///
   /// This is useful when passing a reference to an API which Swift
@@ -65,33 +74,40 @@
   ///
   ///     CFArraySetValueAtIndex(.passUnretained(array), i,
   ///                            .passUnretained(object))
+  ///
+  /// - Parameter value: A class instance.
+  /// - Returns: An unmanaged reference to the object passed as `value`.
   @_transparent
   public static func passUnretained(_ value: Instance) -> Unmanaged {
     return Unmanaged(_private: value)
   }
 
-  /// Get the value of this unmanaged reference as a managed
+  /// Gets the value of this unmanaged reference as a managed
   /// reference without consuming an unbalanced retain of it.
   ///
   /// This is useful when a function returns an unmanaged reference
   /// and you know that you're not responsible for releasing the result.
+  ///
+  /// - Returns: The object referenced by this `Unmanaged` instance.
   public func takeUnretainedValue() -> Instance {
     return _value
   }
 
-  /// Get the value of this unmanaged reference as a managed
-  /// reference and consume an unbalanced retain of it.
+  /// Gets the value of this unmanaged reference as a managed
+  /// reference and consumes an unbalanced retain of it.
   ///
   /// This is useful when a function returns an unmanaged reference
   /// and you know that you're responsible for releasing the result.
+  ///
+  /// - Returns: The object referenced by this `Unmanaged` instance.
   public func takeRetainedValue() -> Instance {
     let result = _value
     release()
     return result
   }
 
-  /// Get the value of the unmanaged referenced as a managed reference without
-  /// consuming an unbalanced retain of it and pass it to the closure. Asserts
+  /// Gets the value of the unmanaged referenced as a managed reference without
+  /// consuming an unbalanced retain of it and passes it to the closure. Asserts
   /// that there is some other reference ('the owning reference') to the
   /// instance referenced by the unmanaged reference that guarantees the
   /// lifetime of the instance for the duration of the
@@ -191,21 +207,21 @@
     return result
   }
 
-  /// Perform an unbalanced retain of the object.
+  /// Performs an unbalanced retain of the object.
   @_transparent
   public func retain() -> Unmanaged {
     Builtin.retain(_value)
     return self
   }
 
-  /// Perform an unbalanced release of the object.
+  /// Performs an unbalanced release of the object.
   @_transparent
   public func release() {
     Builtin.release(_value)
   }
 
 #if _runtime(_ObjC)
-  /// Perform an unbalanced autorelease of the object.
+  /// Performs an unbalanced autorelease of the object.
   @_transparent
   public func autorelease() -> Unmanaged {
     Builtin.autorelease(_value)
diff --git a/stdlib/public/core/UnsafeBufferPointer.swift.gyb b/stdlib/public/core/UnsafeBufferPointer.swift.gyb
index 4ef34f0..b2f4ba2 100644
--- a/stdlib/public/core/UnsafeBufferPointer.swift.gyb
+++ b/stdlib/public/core/UnsafeBufferPointer.swift.gyb
@@ -142,7 +142,7 @@
     return startIndex..<endIndex
   }
 
-  /// Access the `i`th element in the buffer.
+  /// Accesses the `i`th element in the buffer.
   public subscript(i: Int) -> Element {
     get {
       _debugPrecondition(i >= 0)
@@ -177,7 +177,7 @@
 %  end
   }
 
-  /// Construct an Unsafe${Mutable}Pointer over the `count` contiguous
+  /// Creates an Unsafe${Mutable}Pointer over the `count` contiguous
   /// `Element` instances beginning at `start`.
   ///
   /// If `start` is nil, `count` must be 0. However, `count` may be 0 even for
diff --git a/stdlib/public/core/UnsafePointer.swift.gyb b/stdlib/public/core/UnsafePointer.swift.gyb
index e8c8621..2451e80 100644
--- a/stdlib/public/core/UnsafePointer.swift.gyb
+++ b/stdlib/public/core/UnsafePointer.swift.gyb
@@ -40,52 +40,54 @@
   /// The underlying raw (untyped) pointer.
   public let _rawValue: Builtin.RawPointer
 
-  /// Construct ${a_Self} from a builtin raw pointer.
+  /// Creates ${a_Self} from a builtin raw pointer.
   @_transparent
   public init(_ _rawValue : Builtin.RawPointer) {
     self._rawValue = _rawValue
   }
 
-  /// Convert from an opaque pointer to a typed pointer.
+  /// Converts from an opaque pointer to a typed pointer.
   @_transparent
   public init(_ from : OpaquePointer) {
     _rawValue = from._rawValue
   }
 
-  /// Convert from an opaque pointer to a typed pointer.
+  /// Converts from an opaque pointer to a typed pointer.
   ///
-  /// Returns nil if `from` is nil.
+  /// Returns `nil` if `from` is `nil`.
   @_transparent
   public init?(_ from : OpaquePointer?) {
     guard let unwrapped = from else { return nil }
     self.init(unwrapped)
   }
 
-  /// Construct ${a_Self} with a given pattern of bits.
+  /// Creates ${a_Self} with a given pattern of bits.
+  ///
+  /// Returns `nil` if `bitPattern` is zero.
   @_transparent
   public init?(bitPattern: Int) {
     if bitPattern == 0 { return nil }
     self._rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
   }
 
-  /// Construct ${a_Self} with a given pattern of bits.
+  /// Creates ${a_Self} with a given pattern of bits.
   ///
-  /// Returns nil if `bitPattern` is zero.
+  /// Returns `nil` if `bitPattern` is zero.
   @_transparent
   public init?(bitPattern: UInt) {
     if bitPattern == 0 { return nil }
     self._rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
   }
 
-  /// Construct ${a_Self} from another ${a_Self}.
+  /// Creates ${a_Self} from another `${Self}`.
   @_transparent
   public init(_ other: ${Self}<Pointee>) {
     self = other
   }
 
-  /// Construct ${a_Self} from another ${a_Self}.
+  /// Creates ${a_Self} from another `${Self}`.
   ///
-  /// Returns nil if `other` is nil.
+  /// Returns `nil` if `other` is `nil`.
   @_transparent
   public init?(_ other: ${Self}<Pointee>?) {
     guard let unwrapped = other else { return nil }
@@ -93,14 +95,14 @@
   }
 
 %  if mutable:
-  /// Convert from `UnsafePointer` to `UnsafeMutablePointer` of the same
+  /// Converts from `UnsafePointer` to `UnsafeMutablePointer` of the same
   /// `Pointee`.
   @_transparent
   public init(mutating other: UnsafePointer<Pointee>) {
     self._rawValue = other._rawValue
   }
 
-  /// Convert from `UnsafePointer` to `UnsafeMutablePointer` of the same
+  /// Converts from `UnsafePointer` to `UnsafeMutablePointer` of the same
   /// `Pointee`.
   ///
   /// Returns nil if `bitPattern` is zero.
@@ -110,13 +112,13 @@
     self.init(mutating: unwrapped)
   }
 % else:
-  /// Convert from `UnsafeMutablePointer` to ${a_Self} of the same `Pointee`.
+  /// Converts from `UnsafeMutablePointer` to ${a_Self} of the same `Pointee`.
   @_transparent
   public init(_ other: UnsafeMutablePointer<Pointee>) {
     self._rawValue = other._rawValue
   }
 
-  /// Convert from `UnsafeMutablePointer` to ${a_Self} of the same `Pointee`.
+  /// Converts from `UnsafeMutablePointer` to ${a_Self} of the same `Pointee`.
   ///
   /// Returns nil if `from` is nil.
   @_transparent
@@ -127,7 +129,7 @@
 %  end
 
 %  if mutable:
-  /// Allocate and point at uninitialized aligned memory for `count`
+  /// Allocates and points at uninitialized aligned memory for `count`
   /// instances of `Pointee`.
   ///
   /// - Postcondition: The pointee is allocated, but not initialized.
@@ -140,7 +142,7 @@
     return UnsafeMutablePointer(rawPtr)
   }
 
-  /// Deallocate uninitialized memory allocated for `count` instances
+  /// Deallocates uninitialized memory allocated for `count` instances
   /// of `Pointee`.
   ///
   /// - Precondition: The memory is not initialized.
@@ -153,7 +155,7 @@
   }
 %  end
 
-  /// Access the `Pointee` instance referenced by `self`.
+  /// Accesses the `Pointee` instance referenced by `self`.
   ///
   /// - Precondition: the pointee has been initialized with an instance of
   ///   type `Pointee`.
@@ -173,7 +175,7 @@
   }
 
 %  if mutable:
-  /// Initialize `self.pointee` with `count` consecutive copies of `newValue`
+  /// Initializes `self.pointee` with `count` consecutive copies of `newValue`
   ///
   /// - Precondition: The pointee is not initialized.
   ///
@@ -192,7 +194,7 @@
     }
   }
 
-  /// Retrieve the `pointee`, returning the referenced memory to an
+  /// Retrieves the `pointee`, returning the referenced memory to an
   /// uninitialized state.
   ///
   /// Equivalent to `{ defer { deinitialize() }; return pointee }()`, but
@@ -205,7 +207,7 @@
     return Builtin.take(_rawValue)
   }
 
-  /// Replace `count` initialized `Pointee`s starting at `self` with
+  /// Replaces `count` initialized `Pointee`s starting at `self` with
   /// the `count` `Pointee`s at `source`.
   ///
   /// - Precondition: `count >= 0`
@@ -231,7 +233,7 @@
     }
   }
 
-  /// Initialize memory starting at `self` with `count` `Pointee`s
+  /// Initializes memory starting at `self` with `count` `Pointee`s
   /// beginning at `source`, and returning the source memory to an
   /// uninitialized state.
   ///
@@ -269,7 +271,7 @@
     }
   }
 
-  /// Initialize memory starting at `self` with `count` `Pointee`s
+  /// Initializes memory starting at `self` with `count` `Pointee`s
   /// beginning at `source`.
   ///
   /// - Precondition: `count >= 0`
@@ -298,7 +300,7 @@
     // }
   }
 
-  /// Initialize memory starting at `self` with the elements of `source`.
+  /// Initializes memory starting at `self` with the elements of `source`.
   ///
   /// - Precondition: The memory at `self..<self + count` is
   ///   uninitialized.
@@ -310,7 +312,7 @@
     source._copyContents(initializing: self)
   }
 
-  /// Replace `count` initialized `Pointee`s starting at `self` with
+  /// Replaces `count` initialized `Pointee`s starting at `self` with
   /// the `count` `Pointee`s starting at `source`, returning the
   /// source memory to an uninitialized state.
   ///
@@ -340,7 +342,7 @@
     // }
   }
 
-  /// De-initialize the `count` `Pointee`s starting at `self`, returning
+  /// De-initializes the `count` `Pointee`s starting at `self`, returning
   /// their memory to an uninitialized state.
   ///
   /// Returns an UnsafeMutableRawPointer to this memory.
@@ -359,12 +361,11 @@
   }
 %  end
 
-  /// Rebind memory at `self` to type `T` with capacity to hold `count` adjacent
-  /// `T` values while executing the `body` closure. After executing the
-  /// closure, rebind memory back to `Pointee`.
+  /// Rebinds memory at `self` to type `T` with capacity to hold `count`
+  /// adjacent `T` values while executing the `body` closure. After executing
+  /// the closure, rebinds memory back to `Pointee`.
   ///
   /// - Precondition: Type 'T' is layout compatible with type 'Pointee'.
-  ///
   /// - Precondition: The memory `self..<self + count * MemoryLayout<T>.stride`
   ///   is bound to `Pointee`.
   public func withMemoryRebound<T, Result>(to: T.Type, capacity count: Int,
@@ -377,7 +378,7 @@
     return try body(UnsafeMutablePointer<T>(_rawValue))
   }
 
-  /// Access the pointee at `self + i`.
+  /// Accesses the pointee at `self + i`.
   ///
   /// - Precondition: the pointee at `self + i` is initialized.
   public subscript(i: Int) -> Pointee {
@@ -402,13 +403,11 @@
   // Protocol conformance
   //
 
-  /// The hash value.
+  /// The pointer's hash value.
   ///
-  /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
-  ///
-  /// - Note: The hash value is not guaranteed to be stable across
-  ///   different invocations of the same program.  Do not persist the
-  ///   hash value across program runs.
+  /// The hash value is not guaranteed to be stable across different
+  /// invocations of the same program.  Do not persist the hash value across
+  /// program runs.
   public var hashValue: Int {
     return Int(bitPattern: self)
   }
@@ -423,19 +422,19 @@
     return self - 1
   }
 
-  /// Return `end - self`.
+  /// Returns `end - self`.
   public func distance(to x: ${Self}) -> Int {
     return x - self
   }
 
-  /// Return `self + n`.
+  /// Returns `self + n`.
   public func advanced(by n: Int) -> ${Self} {
     return self + n
   }
 }
 
 extension ${Self} : CustomDebugStringConvertible {
-  /// A textual representation of `self`, suitable for debugging.
+  /// A textual representation of the pointer, suitable for debugging.
   public var debugDescription: String {
     return _rawPointerToString(_rawValue)
   }
@@ -517,6 +516,30 @@
 }
 
 extension ${Self} {
+  @available(*, unavailable, message:
+    "use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.")
+  public init<U>(_ from : UnsafeMutablePointer<U>) { Builtin.unreachable() }
+
+  @available(*, unavailable, message:
+    "use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.")
+  public init?<U>(_ from : UnsafeMutablePointer<U>?) { Builtin.unreachable(); return nil }
+
+  @available(*, unavailable, message:
+    "use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.")
+  public init<U>(_ from : UnsafePointer<U>) { Builtin.unreachable() }
+
+  @available(*, unavailable, message:
+    "use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.")
+  public init?<U>(_ from : UnsafePointer<U>?) { Builtin.unreachable(); return nil }
+
+% if mutable:
+  @available(*, unavailable, renamed: "init(mutating:)")
+  public init(_ from : UnsafePointer<Pointee>) { Builtin.unreachable() }
+
+  @available(*, unavailable, renamed: "init(mutating:)")
+  public init?(_ from : UnsafePointer<Pointee>?) { Builtin.unreachable(); return nil }
+% end
+
   @available(*, unavailable, renamed: "Pointee")
   public typealias Memory = Pointee
 
diff --git a/stdlib/public/core/UnsafeRawPointer.swift.gyb b/stdlib/public/core/UnsafeRawPointer.swift.gyb
index a35effd..e086595 100644
--- a/stdlib/public/core/UnsafeRawPointer.swift.gyb
+++ b/stdlib/public/core/UnsafeRawPointer.swift.gyb
@@ -27,65 +27,69 @@
   /// Implements conformance to the public protocol `_Pointer`.
   public let _rawValue: Builtin.RawPointer
 
-  /// Construct ${a_Self} from another ${a_Self}.
+  /// Creates ${a_Self} from another `${Self}`.
   @_transparent
   public init(_ other: Unsafe${Mutable}RawPointer) {
     self = other
   }
 
-  /// Construct ${a_Self} from another ${a_Self}.
+  /// Creates ${a_Self} from another `${Self}`.
   ///
-  /// Returns nil if `other` is nil.
+  /// Returns `nil` if `other` is `nil`.
   @_transparent
   public init?(_ other: Unsafe${Mutable}RawPointer?) {
     guard let unwrapped = other else { return nil }
     self = unwrapped
   }
 
-  /// Convert a builtin raw pointer to ${a_Self}.
+  /// Converts a builtin raw pointer to ${a_Self}.
   @_transparent
   public init(_ _rawValue: Builtin.RawPointer) {
     self._rawValue = _rawValue
   }
 
-  /// Convert an opaque pointer to ${a_Self}.
+  /// Converts an opaque pointer to ${a_Self}.
   @_transparent
   public init(_ other: OpaquePointer) {
     _rawValue = other._rawValue
   }
 
-  /// Convert an opaque pointer to ${a_Self}.
+  /// Converts an opaque pointer to ${a_Self}.
   ///
-  /// Returns nil if `from` is nil.
+  /// Returns `nil` if `from` is `nil`.
   @_transparent
   public init?(_ other: OpaquePointer?) {
     guard let unwrapped = other else { return nil }
     _rawValue = unwrapped._rawValue
   }
 
-  /// Convert a pattern of bits to ${a_Self}.
+  /// Converts a pattern of bits to ${a_Self}.
+  ///
+  /// Returns `nil` if `bitPattern` is zero.
   @_transparent
   public init?(bitPattern: Int) {
     if bitPattern == 0 { return nil }
     _rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
   }
 
-  /// Convert a pattern of bits to ${a_Self}.
+  /// Converts a pattern of bits to ${a_Self}.
+  ///
+  /// Returns `nil` if `bitPattern` is zero.
   @_transparent
   public init?(bitPattern: UInt) {
     if bitPattern == 0 { return nil }
     _rawValue = Builtin.inttoptr_Word(bitPattern._builtinWordValue)
   }
 
-  /// Convert an Unsafe${Mutable}Pointer to ${a_Self}.
+  /// Converts an Unsafe${Mutable}Pointer to ${a_Self}.
   @_transparent
   public init<T>(_ other: Unsafe${Mutable}Pointer<T>) {
     _rawValue = other._rawValue
   }
 
-  /// Convert an Unsafe${Mutable}Pointer to ${a_Self}.
+  /// Converts an Unsafe${Mutable}Pointer to ${a_Self}.
   ///
-  /// Returns nil if `other` is nil.
+  /// Returns `nil` if `other` is `nil`.
   @_transparent
   public init?<T>(_ other: Unsafe${Mutable}Pointer<T>?) {
     guard let unwrapped = other else { return nil }
@@ -93,45 +97,45 @@
   }
 
 %  if mutable:
-  /// Convert an UnsafeRawPointer to ${a_Self}.
+  /// Converts an UnsafeRawPointer to ${a_Self}.
   @_transparent
   public init(mutating other: UnsafeRawPointer) {
     _rawValue = other._rawValue
   }
 
-  /// Convert an UnsafeRawPointer to ${a_Self}.
+  /// Converts an UnsafeRawPointer to ${a_Self}.
   ///
-  /// Returns nil if `other` is nil.
+  /// Returns `nil` if `other` is `nil`.
   @_transparent
   public init?(mutating other: UnsafeRawPointer?) {
     guard let unwrapped = other else { return nil }
     _rawValue = unwrapped._rawValue
   }
 %  else: # !mutable
-  /// Convert an UnsafeMutableRawPointer to ${a_Self}.
+  /// Converts an UnsafeMutableRawPointer to ${a_Self}.
   @_transparent
   public init(_ other: UnsafeMutableRawPointer) {
     _rawValue = other._rawValue
   }
 
-  /// Convert an UnsafeMutableRawPointer to ${a_Self}.
+  /// Converts an UnsafeMutableRawPointer to ${a_Self}.
   ///
-  /// Returns nil if `other` is nil.
+  /// Returns `nil` if `other` is `nil`.
   @_transparent
   public init?(_ other: UnsafeMutableRawPointer?) {
     guard let unwrapped = other else { return nil }
     _rawValue = unwrapped._rawValue
   }
 
-  /// Convert an UnsafeMutablePointer to ${a_Self}.
+  /// Converts an UnsafeMutablePointer to ${a_Self}.
   @_transparent
   public init<T>(_ other: UnsafeMutablePointer<T>) {
     _rawValue = other._rawValue
   }
 
-  /// Convert an UnsafeMutablePointer to ${a_Self}.
+  /// Converts an UnsafeMutablePointer to ${a_Self}.
   ///
-  /// Returns nil if `other` is nil.
+  /// Returns `nil` if `other` is `nil`.
   @_transparent
   public init?<T>(_ other: UnsafeMutablePointer<T>?) {
     guard let unwrapped = other else { return nil }
@@ -140,7 +144,7 @@
 %  end # !mutable
 
 %  if mutable:
-  /// Allocate and point at uninitialized memory for `size` bytes with
+  /// Allocates and points at uninitialized memory for `size` bytes with
   /// `alignedTo` alignment.
   ///
   /// - Postcondition: The memory is allocated, but not initialized.
@@ -151,25 +155,22 @@
   }
 %  end # mutable
 
-  /// Deallocate uninitialized memory allocated for `bytes` number of bytes with
-  /// `alignedTo` alignment.
+  /// Deallocates uninitialized memory allocated for `bytes` number of bytes
+  /// with `alignedTo` alignment.
   ///
   /// - Precondition: The memory is not initialized.
-  ///
   /// - Postcondition: The memory has been deallocated.
   public func deallocate(bytes: Int, alignedTo: Int) {
     Builtin.deallocRaw(
       _rawValue, bytes._builtinWordValue, alignedTo._builtinWordValue)
   }
   
-  /// Binding the allocated memory to type `T`.
-  /// Returns an Unsafe${Mutable}Pointer<T> to the bound memory at `self`.
-  ///  
-  /// - Precondition: The memory is uninitialized.
+  /// Binds the allocated memory to type `T` and returns an
+  /// `Unsafe${Mutable}Pointer<T>` to the bound memory at `self`.
   ///
+  /// - Precondition: The memory is uninitialized.
   /// - Postcondition: The memory is bound to 'T' starting at `self` continuing
   ///   through `self` + `count` * `MemoryLayout<T>.stride`
-  ///
   /// - Warning: Binding memory to a type is potentially undefined if the
   ///   memory is ever accessed as an unrelated type.
   @_transparent
@@ -180,7 +181,7 @@
     return Unsafe${Mutable}Pointer<T>(_rawValue)
   }
 
-  /// Convert from ${a_Self} to Unsafe${Mutable}Pointer<T> given that
+  /// Converts from ${a_Self} to Unsafe${Mutable}Pointer<T> given that
   /// the region of memory starting at `self` is already bound to type `T`.
   ///
   /// - Precondition: The memory is bound to 'T' starting at `self` for some
@@ -194,8 +195,8 @@
   }
 
 %  if mutable:
-  /// Initialize this memory location `self + strideof(T) * index`
-  /// with `count` consecutive copies `value`, and bind the
+  /// Initializes this memory location `self + strideof(T) * index`
+  /// with `count` consecutive copies of `value` and binds the
   /// initialized memory to type `T`.
   ///
   /// Returns an `UnsafeMutablePointer<T>` to this memory.
@@ -233,29 +234,24 @@
     return UnsafeMutablePointer(_rawValue)
   }
 
-  /// Initialize memory starting at `self` with `count` `T` values
-  /// beginning at `source`, and bind the initialized memory to type
-  /// `T`.
+  /// Initializes memory starting at `self` with `count` `T` values beginning
+  /// at `source` and binds the initialized memory to type `T`.
   ///
   /// Returns an `UnsafeMutablePointer<T>` this memory.
   ///
   /// - Precondition: `count >= 0`
-  ///
   /// - Precondition: The memory regions `source..<source + count` and
   ///   `self..<self + count * MemoryLayout<T>.stride` do not overlap.
-  ///
-  /// - Precondition: The memory at `self..<self + count * MemoryLayout<T>.stride`
-  ///   is uninitialized, and the `T` values at `source..<source + count` are
-  ///   initialized.
-  ///
-  /// - Precondition: The underlying pointer is properly aligned for
-  ///                 accessing `T`.
-  ///
-  /// - Postcondition: The memory at `self..<self + count * MemoryLayout<T>.stride`
-  ///   is bound to type `T`.
-  ///
-  /// - Postcondition: The `T` values at `self..<self + count *
-  ///   MemoryLayout<T>.stride` and `source..<source + count` are initialized.
+  /// - Precondition: The memory at
+  ///   `self..<self + count * MemoryLayout<T>.stride` is uninitialized, and
+  ///   the `T` values at `source..<source + count` are initialized.
+  /// - Precondition: The underlying pointer is properly aligned for accessing
+  ///   `T`.
+  /// - Postcondition: The memory at
+  ///   `self..<self + count * MemoryLayout<T>.stride` is bound to type `T`.
+  /// - Postcondition: The `T` values at
+  ///   `self..<self + count * MemoryLayout<T>.stride` and
+  ///   `source..<source + count` are initialized.
   @discardableResult
   public func initializeMemory<T>(
     as type: T.Type, from source: UnsafePointer<T>, count: Int
@@ -279,8 +275,8 @@
     return UnsafeMutablePointer(_rawValue)
   }
 
-  /// Initialize memory starting at `self` with the elements of
-  /// `source`, and bind the initialized memory to type `T`.
+  /// Initializes memory starting at `self` with the elements of
+  /// `source` and binds the initialized memory to type `T`.
   ///
   /// Returns an `UnsafeMutablePointer<T>` this memory.
   ///
@@ -305,9 +301,9 @@
     return UnsafeMutablePointer(_rawValue)
   }
 
-  /// Initialize memory starting at `self` with `count` `T` values
-  /// beginning at `source`, bind the initialized memory to type `T`,
-  /// and return the source memory to an uninitialized state.
+  /// Initializes memory starting at `self` with `count` `T` values
+  /// beginning at `source`, binds the initialized memory to type `T`,
+  /// and returns the source memory to an uninitialized state.
   ///
   /// Returns an `UnsafeMutablePointer<T>` this memory.
   ///
@@ -358,7 +354,7 @@
   }
 %  end # mutable
 
-  /// Read raw bytes from memory at `self + offset` and construct a
+  /// Reads raw bytes from memory at `self + offset` and constructs a
   /// value of type `T`.
   ///
   /// - Precondition: The underlying pointer plus `offset` is properly
@@ -375,7 +371,7 @@
   }
 
 %  if mutable:
-  /// Store a value's bytes into raw memory at `self + offset`.
+  /// Stores a value's bytes into raw memory at `self + offset`.
   ///  
   /// - Precondition: The underlying pointer plus `offset` is properly
   ///   aligned for storing type `T`.
@@ -423,7 +419,7 @@
     }
   }
   
-  /// Copy `count` bytes from `source` into memory at `self`.
+  /// Copies `count` bytes from `source` into memory at `self`.
   ///  
   /// - Precondition: `count` is non-negative.
   ///
@@ -450,24 +446,22 @@
   // Protocol conformance
   //
 
-  /// The hash value.
+  /// The pointer's hash value.
   ///
-  /// **Axiom:** `x == y` implies `x.hashValue == y.hashValue`.
-  ///
-  /// - Note: The hash value is not guaranteed to be stable across
-  ///   different invocations of the same program.  Do not persist the
-  ///   hash value across program runs.
+  /// The hash value is not guaranteed to be stable across different
+  /// invocations of the same program.  Do not persist the hash value across
+  /// program runs.
   public var hashValue: Int {
     return Int(bitPattern: self)
   }
 
-  /// Return `x - self`.
+  /// Returns `x - self`.
   public func distance(to x: ${Self}) -> Int {
     return Int(Builtin.sub_Word(Builtin.ptrtoint_Word(x._rawValue),
         Builtin.ptrtoint_Word(_rawValue)))
   }
 
-  /// Return `self + n`.
+  /// Returns `self + n`.
   public func advanced(by n: Int) -> ${Self} {
     return ${Self}(Builtin.gep_Word(_rawValue, n._builtinWordValue))
   }
@@ -487,7 +481,7 @@
 }
 
 extension Unsafe${Mutable}RawPointer : CustomDebugStringConvertible {
-  /// A textual representation of `self`, suitable for debugging.
+  /// A textual representation of the pointer, suitable for debugging.
   public var debugDescription: String {
     return _rawPointerToString(_rawValue)
   }
@@ -549,3 +543,16 @@
 
 % end # for mutable
 
+extension UnsafeMutableRawPointer {
+  @available(*, unavailable, renamed: "init(mutating:)")
+  public init(_ from : UnsafeRawPointer) { Builtin.unreachable() }
+
+  @available(*, unavailable, renamed: "init(mutating:)")
+  public init?(_ from : UnsafeRawPointer?) { Builtin.unreachable(); return nil }
+
+  @available(*, unavailable, renamed: "init(mutating:)")
+  public init<T>(_ from : UnsafePointer<T>) { Builtin.unreachable() }
+
+  @available(*, unavailable, renamed: "init(mutating:)")
+  public init?<T>(_ from : UnsafePointer<T>?) { Builtin.unreachable(); return nil }
+}
diff --git a/stdlib/public/core/VarArgs.swift b/stdlib/public/core/VarArgs.swift
index fc7f370..08cd194 100644
--- a/stdlib/public/core/VarArgs.swift
+++ b/stdlib/public/core/VarArgs.swift
@@ -94,7 +94,7 @@
 /// - Warning: This function is best avoided in favor of
 ///   `withVaList`, but occasionally (i.e. in a `class` initializer) you
 ///   may find that the language rules don't allow you to use
-/// `withVaList` as intended.
+///   `withVaList` as intended.
 public func getVaList(_ args: [CVarArg]) -> CVaListPointer {
   let builder = _VaListBuilder()
   for a in args {
diff --git a/stdlib/public/core/Zip.swift b/stdlib/public/core/Zip.swift
index 50b501c..ce96f3b 100644
--- a/stdlib/public/core/Zip.swift
+++ b/stdlib/public/core/Zip.swift
@@ -10,9 +10,37 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A sequence of pairs built out of two underlying sequences, where
-/// the elements of the `i`th pair are the `i`th elements of each
-/// underlying sequence.
+/// Creates a sequence of pairs built out of two underyling sequences.
+///
+/// In the `Zip2Sequence` instance returned by this function, the elements of
+/// the *i*th pair are the *i*th elements of each underlying sequence. The
+/// following example uses the `zip(_:_:)` function to iterate over an array
+/// of strings and a countable range at the same time:
+///
+///     let words = ["one", "two", "three", "four"]
+///     let numbers = 1...4
+///
+///     for (word, number) in zip(words, numbers) {
+///         print("\(word): \(number)")
+///     }
+///     // Prints "one: 1"
+///     // Prints "two: 2
+///     // Prints "three: 3"
+///     // Prints "four: 4"
+///
+/// If the two sequences passed to `zip(_:_:)` are different lengths, the
+/// resulting sequence is the same length as the shorter sequence. In this
+/// example, the resulting array is the same length as `words`:
+///
+///     let naturalNumbers = 1...Int.max
+///     let zipped = Array(zip(words, naturalNumbers))
+///     // zipped == [("one", 1), ("two", 2), ("three", 3), ("four", 4)]
+///
+/// - Parameters:
+///   - sequence1: The first sequence or collection to zip.
+///   - sequence2: The second sequence or collection to zip.
+/// - Returns: A sequence of tuple pairs, where the elements of each pair are
+///   corresponding elements of `sequence1` and `sequence2`.
 public func zip<Sequence1 : Sequence, Sequence2 : Sequence>(
   _ sequence1: Sequence1, _ sequence2: Sequence2
 ) -> Zip2Sequence<Sequence1, Sequence2> {
@@ -26,7 +54,7 @@
   /// The type of element returned by `next()`.
   public typealias Element = (Iterator1.Element, Iterator2.Element)
 
-  /// Construct around a pair of underlying iterators.
+  /// Creates an instance around a pair of underlying iterators.
   internal init(_ iterator1: Iterator1, _ iterator2: Iterator2) {
     (_baseStream1, _baseStream2) = (iterator1, iterator2)
   }
@@ -35,9 +63,6 @@
   /// exists.
   ///
   /// Once `nil` has been returned, all subsequent calls return `nil`.
-  ///
-  /// - Precondition: `next()` has not been applied to a copy of `self`
-  ///   since the copy was made.
   public mutating func next() -> Element? {
     // The next() function needs to track if it has reached the end.  If we
     // didn't, and the first sequence is longer than the second, then when we
@@ -63,9 +88,27 @@
   internal var _reachedEnd: Bool = false
 }
 
-/// A sequence of pairs built out of two underlying sequences, where
-/// the elements of the `i`th pair are the `i`th elements of each
-/// underlying sequence.
+/// A sequence of pairs built out of two underlying sequences.
+///
+/// In a `Zip2Sequence` instance, the elements of the *i*th pair are the *i*th
+/// elements of each underlying sequence. To create a `Zip2Sequence` instance,
+/// use the `zip(_:_:)` function.
+///
+/// The following example uses the `zip(_:_:)` function to iterate over an
+/// array of strings and a countable range at the same time:
+///
+///     let words = ["one", "two", "three", "four"]
+///     let numbers = 1...4
+///
+///     for (word, number) in zip(words, numbers) {
+///         print("\(word): \(number)")
+///     }
+///     // Prints "one: 1"
+///     // Prints "two: 2
+///     // Prints "three: 3"
+///     // Prints "four: 4"
+///
+/// - SeeAlso: `zip(_:_:)`
 public struct Zip2Sequence<Sequence1 : Sequence, Sequence2 : Sequence>
   : Sequence {
 
@@ -79,7 +122,7 @@
   @available(*, unavailable, renamed: "Iterator")
   public typealias Generator = Iterator
 
-  /// Construct an instance that makes pairs of elements from `sequence1` and
+  /// Creates an instance that makes pairs of elements from `sequence1` and
   /// `sequence2`.
   public // @testable
   init(_sequence1 sequence1: Sequence1, _sequence2 sequence2: Sequence2) {
@@ -87,8 +130,6 @@
   }
 
   /// Returns an iterator over the elements of this sequence.
-  ///
-  /// - Complexity: O(1).
   public func makeIterator() -> Iterator {
     return Iterator(
       _sequence1.makeIterator(),
diff --git a/test/1_stdlib/BridgeNonVerbatim.swift b/test/1_stdlib/BridgeNonVerbatim.swift
index 9400740..67bb904 100644
--- a/test/1_stdlib/BridgeNonVerbatim.swift
+++ b/test/1_stdlib/BridgeNonVerbatim.swift
@@ -23,8 +23,9 @@
 
 import Swift
 import SwiftShims
-import ObjectiveC
+import Foundation
 import StdlibUnittest
+import StdlibUnittestFoundationExtras
 
 struct X : _ObjectiveCBridgeable {
   init(_ value: Int) {
@@ -65,7 +66,7 @@
 
 func testScope() {
   let a = [X(1), X(2), X(3)]
-  let nsx = a._buffer._asCocoaArray()
+  let nsx: NSArray = a._bridgeToObjectiveC()
 
   // construction of these tracked objects is lazy
   // CHECK-NEXT: trackedCount = 0 .
@@ -73,12 +74,12 @@
 
   // We can get a single element out
   // CHECK-NEXT: nsx[0]: 1 .
-  let one = nsx.objectAt(0) as! LifetimeTracked
+  let one = nsx.object(at: 0) as! LifetimeTracked
   print("nsx[0]: \(one.value) .")
 
   // We can get the element again, but it may not have the same identity
   // CHECK-NEXT: object identity matches?
-  let anotherOne = nsx.objectAt(0) as! LifetimeTracked
+  let anotherOne = nsx.object(at: 0) as! LifetimeTracked
   print("object identity matches? \(one === anotherOne)")
 
   // Because the elements come back at +0, we really don't want to
@@ -88,9 +89,10 @@
   objects.withUnsafeMutableBufferPointer {
     // FIXME: Can't elide signature and use $0 here <rdar://problem/17770732> 
     (buf: inout UnsafeMutableBufferPointer<Int>) -> () in
-    let objPtr = UnsafeMutableRawPointer(buf.baseAddress!).bindMemory(
-      to: AnyObject.self, capacity: 2)
-    nsx.getObjects(objPtr, range: _SwiftNSRange(location: 1, length: 2))
+    nsx.available_getObjects(
+      AutoreleasingUnsafeMutablePointer(buf.baseAddress!),
+      range: NSRange(location: 1, length: 2))
+    return
   }
 
   // CHECK-NEXT: getObjects yields them at +0: true
diff --git a/test/1_stdlib/CollectionCasts.swift.gyb b/test/1_stdlib/CollectionCasts.swift.gyb
index f893ce3..60bdee4 100644
--- a/test/1_stdlib/CollectionCasts.swift.gyb
+++ b/test/1_stdlib/CollectionCasts.swift.gyb
@@ -1,4 +1,4 @@
-//===--- CollectionCasts.swift.gyb ----------------------------------------===//
+//===--- CollectionCasts.swift.gyb ----------------------------*- swift -*-===//
 //
 // This source file is part of the Swift.org open source project
 //
diff --git a/test/1_stdlib/UnsafePointerDiagnostics.swift b/test/1_stdlib/UnsafePointerDiagnostics.swift
new file mode 100644
index 0000000..ce10abc
--- /dev/null
+++ b/test/1_stdlib/UnsafePointerDiagnostics.swift
@@ -0,0 +1,80 @@
+// RUN: %target-parse-verify-swift
+
+// Test availability attributes on UnsafePointer initializers.
+// Assume the original source contains no UnsafeRawPointer types.
+//
+// TODO:
+// - implement the Unsafe[Mutable]Pointer<Void> to Unsafe[Mutable]RawPointer rename
+// - test multiple fix-its per line: type rename + initializer rename/diagnostic
+func unsafePointerConversionAvailability(
+  mrp: UnsafeMutableRawPointer,
+  rp: UnsafeRawPointer,
+  umpv: UnsafeMutablePointer<Void>,
+  upv: UnsafePointer<Void>,
+  umpi: UnsafeMutablePointer<Int>,
+  upi: UnsafePointer<Int>,
+  umps: UnsafeMutablePointer<String>,
+  ups: UnsafePointer<String>) {
+
+  _ = UnsafeMutableRawPointer(mrp)
+  _ = UnsafeMutableRawPointer(rp)   // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+  _ = UnsafeMutableRawPointer(umpv)
+  _ = UnsafeMutableRawPointer(upv)  // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+  _ = UnsafeMutableRawPointer(umpi)
+  _ = UnsafeMutableRawPointer(upi)  // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+  _ = UnsafeMutableRawPointer(umps)
+  _ = UnsafeMutableRawPointer(ups)  // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+
+  // These all correctly pass with no error.
+  _ = UnsafeRawPointer(mrp)
+  _ = UnsafeRawPointer(rp)
+  _ = UnsafeRawPointer(umpv)
+  _ = UnsafeRawPointer(upv)
+  _ = UnsafeRawPointer(umpi)
+  _ = UnsafeRawPointer(upi)
+  _ = UnsafeRawPointer(umps)
+  _ = UnsafeRawPointer(ups)
+
+  // FIXME: All of these should yield a fix-it to rename
+  // UnsafeMutablePointer<Void> to UnsafeMutableRawPointer(umpv)
+  _ = UnsafeMutablePointer<Void>(rp) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<Void>' with an argument list of type '(UnsafeRawPointer)'}} expected-note {{}}
+  _ = UnsafeMutablePointer<Void>(mrp) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<Void>' with an argument list of type '(UnsafeMutableRawPointer)'}} expected-note {{}}
+  _ = UnsafeMutablePointer<Void>(umpv)
+  _ = UnsafeMutablePointer<Void>(upv)  // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+  _ = UnsafeMutablePointer<Void>(umpi)
+  _ = UnsafeMutablePointer<Void>(upi)  // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+  _ = UnsafeMutablePointer<Void>(umps)
+  _ = UnsafeMutablePointer<Void>(ups)  // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+
+  // FIXME: All of these should yield a fix-it to rename
+  // UnsafePointer<Void> to UnsafeRawPointer(umpv)
+  _ = UnsafePointer<Void>(rp)  // expected-error {{cannot invoke initializer for type 'UnsafePointer<Void>' with an argument list of type '(UnsafeRawPointer)'}} expected-note {{}}
+  _ = UnsafePointer<Void>(mrp) // expected-error {{cannot invoke initializer for type 'UnsafePointer<Void>' with an argument list of type '(UnsafeMutableRawPointer)'}} expected-note {{}}
+  _ = UnsafePointer<Void>(umpv) 
+  _ = UnsafePointer<Void>(upv)
+  _ = UnsafePointer<Void>(umpi)
+  _ = UnsafePointer<Void>(upi)
+  _ = UnsafePointer<Void>(umps)
+  _ = UnsafePointer<Void>(ups)
+
+  // FIXME: Conversion from UnsafePointer<Void> or UnsafeRawPointer to a typed
+  // pointer should have a diagnostic: 'init' is unavailable: Conversion
+  // restricted. Use 'assumingMemoryBound(to:)' or 'bindMemory(to:capacity:)'
+  _ = UnsafeMutablePointer<Int>(rp) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<Int>' with an argument list of type '(UnsafeRawPointer)'}} expected-note {{}}
+  _ = UnsafeMutablePointer<Int>(mrp) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<Int>' with an argument list of type '(UnsafeMutableRawPointer)'}} expected-note {{}}
+  _ = UnsafeMutablePointer<Int>(umpv) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+  _ = UnsafeMutablePointer<Int>(upv)  // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+  _ = UnsafeMutablePointer<Int>(umpi)
+  _ = UnsafeMutablePointer<Int>(upi)  // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+  _ = UnsafeMutablePointer<Int>(umps) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+  _ = UnsafeMutablePointer<Int>(ups)  // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+
+  _ = UnsafePointer<Int>(rp)  // expected-error {{cannot invoke initializer for type 'UnsafePointer<Int>' with an argument list of type '(UnsafeRawPointer)'}} expected-note {{}}
+  _ = UnsafePointer<Int>(mrp) // expected-error {{cannot invoke initializer for type 'UnsafePointer<Int>' with an argument list of type '(UnsafeMutableRawPointer)'}} expected-note {{}}
+  _ = UnsafePointer<Int>(umpv) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+  _ = UnsafePointer<Int>(upv)  // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+  _ = UnsafePointer<Int>(umpi)
+  _ = UnsafePointer<Int>(upi)
+  _ = UnsafePointer<Int>(umps) // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+  _ = UnsafePointer<Int>(ups)  // expected-error {{'init' is unavailable: use 'withMemoryRebound(to:capacity:_)' to temporarily view memory as another layout-compatible type.}}
+}
diff --git a/test/AutolinkExtract/empty.swift b/test/AutolinkExtract/empty.swift
index 8dd98ea..2e32546 100644
--- a/test/AutolinkExtract/empty.swift
+++ b/test/AutolinkExtract/empty.swift
@@ -4,3 +4,4 @@
 // REQUIRES: autolink-extract
 
 // CHECK-elf: -lswiftCore
+// CHECK-coff: -lswiftCore
diff --git a/test/AutolinkExtract/empty_archive.swift b/test/AutolinkExtract/empty_archive.swift
index 54ebece..030ef63 100644
--- a/test/AutolinkExtract/empty_archive.swift
+++ b/test/AutolinkExtract/empty_archive.swift
@@ -6,3 +6,4 @@
 // REQUIRES: autolink-extract
 
 // CHECK-elf: -lswiftCore
+// CHECK-coff: -lswiftCore
diff --git a/test/AutolinkExtract/import.swift b/test/AutolinkExtract/import.swift
index 225dfff..c87a7bc 100644
--- a/test/AutolinkExtract/import.swift
+++ b/test/AutolinkExtract/import.swift
@@ -9,4 +9,7 @@
 // CHECK-elf-DAG: -lswiftCore
 // CHECK-elf-DAG: -lempty
 
+// CHECK-coff-DAG: -lswiftCore
+// CHECK-coff-DAG: -lempty
+
 import empty
diff --git a/test/AutolinkExtract/import_archive.swift b/test/AutolinkExtract/import_archive.swift
index 0cba4a1..d3fa6a6 100644
--- a/test/AutolinkExtract/import_archive.swift
+++ b/test/AutolinkExtract/import_archive.swift
@@ -10,4 +10,7 @@
 // CHECK-elf-DAG: -lswiftCore
 // CHECK-elf-DAG: -lempty
 
+// CHECK-coff-DAG: -lswiftCore
+// CHECK-coff-DAG: -lempty
+
 import empty
diff --git a/test/AutolinkExtract/linker-order.ll b/test/AutolinkExtract/linker-order.ll
index 8f84a20..7da7d60 100644
--- a/test/AutolinkExtract/linker-order.ll
+++ b/test/AutolinkExtract/linker-order.ll
@@ -1,4 +1,6 @@
 ; RUN: llc -mtriple armv7--linux-gnueabihf -filetype obj -o - %s | %target-swift-autolink-extract -o - - | FileCheck %s
+; RUN: llc -mtriple x86_64--windows-gnu -filetype obj -o - %s | %target-swift-autolink-extract -o - - | FileCheck %s
+; RUN: llc -mtriple x86_64--windows-cygnus -filetype obj -o - %s | %target-swift-autolink-extract -o - - | FileCheck %s
 ; REQUIRES: autolink-extract
 
 ; Ensure that the options in the object file preserve ordering.  The linker
diff --git a/test/Constraints/diagnostics.swift b/test/Constraints/diagnostics.swift
index 0235bad..beaa533 100644
--- a/test/Constraints/diagnostics.swift
+++ b/test/Constraints/diagnostics.swift
@@ -412,7 +412,7 @@
 
 // <rdar://problem/20491794> Error message does not tell me what the problem is
 enum Color {
-  case Red // expected-note 2 {{did you mean 'Red'?}}
+  case Red
   case Unknown(description: String)
 
   static func rainbow() -> Color {}
@@ -446,8 +446,8 @@
 let _: Color = .frob(1, b: i)  // expected-error {{passing value of type 'Int' to an inout parameter requires explicit '&'}}
 let _: Color = .frob(1, &d) // expected-error {{cannot convert value of type 'Double' to expected argument type 'Int'}}
 let _: Color = .frob(1, b: &d) // expected-error {{cannot convert value of type 'Double' to expected argument type 'Int'}}
-var someColor : Color = .red // expected-error {{type 'Color' has no member 'red'}}
-someColor = .red  // expected-error {{type 'Color' has no member 'red'}}
+var someColor : Color = .red // expected-error {{enum type 'Color' has no case 'red'; did you mean 'Red'}}
+someColor = .red  // expected-error {{enum type 'Color' has no case 'red'; did you mean 'Red'}}
 
 func testTypeSugar(_ a : Int) {
   typealias Stride = Int
diff --git a/test/Interpreter/SDK/objc_fast_enumeration.swift b/test/Interpreter/SDK/objc_fast_enumeration.swift
index 53e90c3..fba5d7d 100644
--- a/test/Interpreter/SDK/objc_fast_enumeration.swift
+++ b/test/Interpreter/SDK/objc_fast_enumeration.swift
@@ -91,7 +91,7 @@
 // CHECK: 2
 // CHECK: 1
 var a2 = [3, 2, 1]
-var nsa2 = (a2._buffer._asCocoaArray() as AnyObject) as! NSArray
+var nsa2: NSArray = a2._bridgeToObjectiveC()
 for x in nsa2 {
   print(x)
 }
@@ -107,7 +107,7 @@
 // CHECK: X(2)
 // CHECK: X(1)
 var a3 = [X(3), X(2), X(1)]
-var nsa3 = (a3._buffer._asCocoaArray() as AnyObject) as! NSArray
+var nsa3: NSArray = a3._bridgeToObjectiveC()
 for x in nsa3 {
   print(x)
 }
diff --git a/test/NameBinding/accessibility.swift b/test/NameBinding/accessibility.swift
index 68c3fe8..fbba954 100644
--- a/test/NameBinding/accessibility.swift
+++ b/test/NameBinding/accessibility.swift
@@ -16,7 +16,7 @@
 #endif
 
 // This deliberately has the wrong import kind.
-import var has_accessibility.zz // expected-error {{no such decl in module}}
+import var has_accessibility.zz // expected-error {{variable 'zz' does not exist in module 'has_accessibility'}}
 
 func markUsed<T>(_ t: T) {}
 
diff --git a/test/NameBinding/name_lookup.swift b/test/NameBinding/name_lookup.swift
index 8b94566..964f784 100644
--- a/test/NameBinding/name_lookup.swift
+++ b/test/NameBinding/name_lookup.swift
@@ -522,7 +522,8 @@
 enum MyEnum {
   case one
   case two
-  
+  case oneTwoThree
+
   static let kMyConstant = "myConstant"
 }
 
@@ -535,3 +536,8 @@
   break
 }
 
+func foo() {
+  _ = MyEnum.One // expected-error {{enum type 'MyEnum' has no case 'One'; did you mean 'one'}}{{14-17=one}}
+  _ = MyEnum.Two // expected-error {{enum type 'MyEnum' has no case 'Two'; did you mean 'two'}}{{14-17=two}}
+  _ = MyEnum.OneTwoThree // expected-error {{enum type 'MyEnum' has no case 'OneTwoThree'; did you mean 'oneTwoThree'}}{{14-25=oneTwoThree}}
+}
diff --git a/test/Prototypes/Algorithms.swift.gyb b/test/Prototypes/Algorithms.swift.gyb
index 7e96e7c..0047fa3 100644
--- a/test/Prototypes/Algorithms.swift.gyb
+++ b/test/Prototypes/Algorithms.swift.gyb
@@ -1,4 +1,4 @@
-//===--- Algorithms.swift.gyb ---------------------------------------------===//
+//===--- Algorithms.swift.gyb ---------------------------------*- swift -*-===//
 //
 // This source file is part of the Swift.org open source project
 //
diff --git a/test/Sema/diag_init.swift b/test/Sema/diag_init.swift
index 96685e1..5f97333 100644
--- a/test/Sema/diag_init.swift
+++ b/test/Sema/diag_init.swift
@@ -1,5 +1,5 @@
 // RUN: %target-parse-verify-swift
 
 func foo(a :  UnsafePointer<Void>)->UnsafeMutablePointer<Void> {
-  return UnsafeMutablePointer(a) // expected-error {{cannot invoke initializer for type 'UnsafeMutablePointer<_>' with an argument list of type '(UnsafePointer<Void>)'}} // expected-note {{do you want to add 'mutating'}}{{31-31=mutating: }} // expected-note {{overloads for 'UnsafeMutablePointer<_>' exist with these partially matching parameter lists: (RawPointer), (OpaquePointer), (OpaquePointer?), (UnsafeMutablePointer<Pointee>), (UnsafeMutablePointer<Pointee>?)}}
-}
\ No newline at end of file
+  return UnsafeMutablePointer(a) // expected-error {{'init' has been renamed to 'init(mutating:)'}}
+}
diff --git a/test/SourceKit/DocSupport/doc_clang_module.swift.response b/test/SourceKit/DocSupport/doc_clang_module.swift.response
index 38dcef1..0c5e104 100644
--- a/test/SourceKit/DocSupport/doc_clang_module.swift.response
+++ b/test/SourceKit/DocSupport/doc_clang_module.swift.response
@@ -5487,7 +5487,7 @@
         key.name: "insert(_:)",
         key.usr: "s:FesRxs9OptionSetxzwx7ElementrS_6insertFwxS0_T8insertedSb17memberAfterInsertwxS0__::SYNTHESIZED::c:@E@FooRuncingOptions",
         key.original_usr: "s:FesRxs9OptionSetxzwx7ElementrS_6insertFwxS0_T8insertedSb17memberAfterInsertwxS0__",
-        key.doc.full_as_xml: "<Function><Name>insert(_:)</Name><USR>s:FesRxs9OptionSetxzwx7ElementrS_6insertFwxS0_T8insertedSb17memberAfterInsertwxS0__</USR><Declaration>mutating func insert(_ newMember: Self) -&gt; (inserted: Bool, memberAfterInsert: Self)</Declaration><Abstract><Para>Inserts the given element into the option set if it is not already a member.</Para></Abstract><Parameters><Parameter><Name>newMember</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>The element to insert.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>(true, newMember)</codeVoice> if <codeVoice>newMember</codeVoice> was not contained in <codeVoice>self</codeVoice>. Otherwise, returns <codeVoice>(false, oldMember)</codeVoice>, where <codeVoice>oldMember</codeVoice> is the member of the set equal to <codeVoice>newMember</codeVoice>.</Para></ResultDiscussion><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let purchasePrice = 87.55]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[var freeOptions: ShippingOptions = [.standard, .priority]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[if purchasePrice > 50 {]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[    freeOptions.insert(.secondDay)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[}]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(freeOptions.contains(.secondDay))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+        key.doc.full_as_xml: "<Function><Name>insert(_:)</Name><USR>s:FesRxs9OptionSetxzwx7ElementrS_6insertFwxS0_T8insertedSb17memberAfterInsertwxS0__</USR><Declaration>mutating func insert(_ newMember: Self) -&gt; (inserted: Bool, memberAfterInsert: Self)</Declaration><Abstract><Para>Adds the given element to the option set if it is not already a member.</Para></Abstract><Parameters><Parameter><Name>newMember</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>The element to insert.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>(true, newMember)</codeVoice> if <codeVoice>newMember</codeVoice> was not contained in <codeVoice>self</codeVoice>. Otherwise, returns <codeVoice>(false, oldMember)</codeVoice>, where <codeVoice>oldMember</codeVoice> is the member of the set equal to <codeVoice>newMember</codeVoice>.</Para></ResultDiscussion><Discussion><Para>In the following example, the <codeVoice>.secondDay</codeVoice> shipping option is added to the <codeVoice>freeOptions</codeVoice> option set if <codeVoice>purchasePrice</codeVoice> is greating than 50. For the <codeVoice>ShippingOptions</codeVoice> declaration, see the <codeVoice>OptionSet</codeVoice> protocol discussion.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let purchasePrice = 87.55]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[var freeOptions: ShippingOptions = [.standard, .priority]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[if purchasePrice > 50 {]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[    freeOptions.insert(.secondDay)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[}]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(freeOptions.contains(.secondDay))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
         key.offset: 1962,
         key.length: 110,
         key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.attribute.builtin><syntaxtype.attribute.name>@discardableResult</syntaxtype.attribute.name></syntaxtype.attribute.builtin> <syntaxtype.keyword>mutating</syntaxtype.keyword> <syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>insert</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>_</decl.var.parameter.argument_label> <decl.var.parameter.name>newMember</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -&gt; <decl.function.returntype><tuple>(<tuple.element><tuple.element.argument_label>inserted</tuple.element.argument_label>: <tuple.element.type><ref.struct usr=\"s:Sb\">Bool</ref.struct></tuple.element.type></tuple.element>, <tuple.element><tuple.element.argument_label>memberAfterInsert</tuple.element.argument_label>: <tuple.element.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></tuple.element.type></tuple.element>)</tuple></decl.function.returntype></decl.function.method.instance>",
@@ -5506,7 +5506,7 @@
         key.name: "remove(_:)",
         key.usr: "s:FesRxs9OptionSetxzwx7ElementrS_6removeFwxS0_GSqwxS0__::SYNTHESIZED::c:@E@FooRuncingOptions",
         key.original_usr: "s:FesRxs9OptionSetxzwx7ElementrS_6removeFwxS0_GSqwxS0__",
-        key.doc.full_as_xml: "<Function><Name>remove(_:)</Name><USR>s:FesRxs9OptionSetxzwx7ElementrS_6removeFwxS0_GSqwxS0__</USR><Declaration>mutating func remove(_ member: Self) -&gt; Self?</Declaration><Abstract><Para>Removes the given element and all elements subsumed by the given element.</Para></Abstract><Parameters><Parameter><Name>member</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>The element of the set to remove.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>The intersection of <codeVoice>[member]</codeVoice> and the set if the intersection was nonempty; otherwise, <codeVoice>nil</codeVoice>.</Para></ResultDiscussion><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[var options: ShippingOptions = [.secondDay, .priority]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let priorityOption = options.remove(.priority)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(priorityOption == .priority)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(options.remove(.priority))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"nil\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing><Para>In the following example, the <codeVoice>.express</codeVoice> element is passed to <codeVoice>remove(_:)</codeVoice>. Although <codeVoice>.express</codeVoice> is not a member of <codeVoice>options</codeVoice>, <codeVoice>.express</codeVoice> subsumes the remaining <codeVoice>.secondDay</codeVoice> element of the option set. Therefore, <codeVoice>options</codeVoice> is emptied and the intersection between <codeVoice>.express</codeVoice> and <codeVoice>options</codeVoice> is returned.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let expressOption = options.remove(.express)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(expressOption == .express)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"false\"]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(expressOption == .secondDay)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+        key.doc.full_as_xml: "<Function><Name>remove(_:)</Name><USR>s:FesRxs9OptionSetxzwx7ElementrS_6removeFwxS0_GSqwxS0__</USR><Declaration>mutating func remove(_ member: Self) -&gt; Self?</Declaration><Abstract><Para>Removes the given element and all elements subsumed by the given element.</Para></Abstract><Parameters><Parameter><Name>member</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>The element of the set to remove.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>The intersection of <codeVoice>[member]</codeVoice> and the set if the intersection was nonempty; otherwise, <codeVoice>nil</codeVoice>.</Para></ResultDiscussion><Discussion><Para>In the following example, the <codeVoice>.priority</codeVoice> shipping option is removed from the <codeVoice>options</codeVoice> option set. Attempting to remove the same shipping option a second time results in <codeVoice>nil</codeVoice>, because <codeVoice>options</codeVoice> no longer contains <codeVoice>.priority</codeVoice> as a member.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[var options: ShippingOptions = [.secondDay, .priority]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let priorityOption = options.remove(.priority)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(priorityOption == .priority)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(options.remove(.priority))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"nil\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing><Para>In the next example, the <codeVoice>.express</codeVoice> element is passed to <codeVoice>remove(_:)</codeVoice>. Although <codeVoice>.express</codeVoice> is not a member of <codeVoice>options</codeVoice>, <codeVoice>.express</codeVoice> subsumes the remaining <codeVoice>.secondDay</codeVoice> element of the option set. Therefore, <codeVoice>options</codeVoice> is emptied and the intersection between <codeVoice>.express</codeVoice> and <codeVoice>options</codeVoice> is returned.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let expressOption = options.remove(.express)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(expressOption == .express)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"false\"]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(expressOption == .secondDay)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
         key.offset: 2078,
         key.length: 71,
         key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.attribute.builtin><syntaxtype.attribute.name>@discardableResult</syntaxtype.attribute.name></syntaxtype.attribute.builtin> <syntaxtype.keyword>mutating</syntaxtype.keyword> <syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>remove</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>_</decl.var.parameter.argument_label> <decl.var.parameter.name>member</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -&gt; <decl.function.returntype><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct>?</decl.function.returntype></decl.function.method.instance>",
@@ -5691,7 +5691,7 @@
         key.name: "subtract(_:)",
         key.usr: "s:FEsPs10SetAlgebra8subtractFxT_::SYNTHESIZED::c:@E@FooRuncingOptions",
         key.original_usr: "s:FEsPs10SetAlgebra8subtractFxT_",
-        key.doc.full_as_xml: "<Function><Name>subtract(_:)</Name><USR>s:FEsPs10SetAlgebra8subtractFxT_</USR><Declaration>mutating func subtract(_ other: Self)</Declaration><Abstract><Para>Removes the elements of the given set from this set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[var employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let neighbors: Set = [\"Bethany\", \"Eric\", \"Forlani\", \"Greta\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[employees.subtract(neighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"[\"Diana\", \"Chris\", \"Alicia\"]\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+        key.doc.full_as_xml: "<Function><Name>subtract(_:)</Name><USR>s:FEsPs10SetAlgebra8subtractFxT_</USR><Declaration>mutating func subtract(_ other: Self)</Declaration><Abstract><Para>Removes the elements of the given set from this set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><Discussion><Para>In the following example, the elements of the <codeVoice>employees</codeVoice> set that are also members of the <codeVoice>neighbors</codeVoice> set are removed. In particular, the names <codeVoice>&quot;Bethany&quot;</codeVoice> and <codeVoice>&quot;Eric&quot;</codeVoice> are removed from <codeVoice>employees</codeVoice>.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[var employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let neighbors: Set = [\"Bethany\", \"Eric\", \"Forlani\", \"Greta\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[employees.subtract(neighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"[\"Diana\", \"Chris\", \"Alicia\"]\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
         key.offset: 2688,
         key.length: 50,
         key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.keyword>mutating</syntaxtype.keyword> <syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>subtract</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>_</decl.var.parameter.argument_label> <decl.var.parameter.name>other</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>)</decl.function.method.instance>",
@@ -5748,7 +5748,7 @@
         key.name: "isDisjoint(with:)",
         key.usr: "s:FEsPs10SetAlgebra10isDisjointFT4withx_Sb::SYNTHESIZED::c:@E@FooRuncingOptions",
         key.original_usr: "s:FEsPs10SetAlgebra10isDisjointFT4withx_Sb",
-        key.doc.full_as_xml: "<Function><Name>isDisjoint(with:)</Name><USR>s:FEsPs10SetAlgebra10isDisjointFT4withx_Sb</USR><Declaration>func isDisjoint(with other: Self) -&gt; Bool</Declaration><Abstract><Para>Returns a Boolean value that indicates whether the set has no members in common with the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>true</codeVoice> if the set has no elements in common with <codeVoice>other</codeVoice>; otherwise, <codeVoice>false</codeVoice>.</Para></ResultDiscussion><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let visitors: Set = [\"Marcia\", \"Nathaniel\", \"Olivia\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isDisjoint(with: visitors))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+        key.doc.full_as_xml: "<Function><Name>isDisjoint(with:)</Name><USR>s:FEsPs10SetAlgebra10isDisjointFT4withx_Sb</USR><Declaration>func isDisjoint(with other: Self) -&gt; Bool</Declaration><Abstract><Para>Returns a Boolean value that indicates whether the set has no members in common with the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>true</codeVoice> if the set has no elements in common with <codeVoice>other</codeVoice>; otherwise, <codeVoice>false</codeVoice>.</Para></ResultDiscussion><Discussion><Para>In the following example, the <codeVoice>employees</codeVoice> set is disjoint with the <codeVoice>visitors</codeVoice> set because no name appears in both sets.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let visitors: Set = [\"Marcia\", \"Nathaniel\", \"Olivia\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isDisjoint(with: visitors))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
         key.offset: 2858,
         key.length: 54,
         key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>isDisjoint</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>with</decl.var.parameter.argument_label> <decl.var.parameter.name>other</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -&gt; <decl.function.returntype><ref.struct usr=\"s:Sb\">Bool</ref.struct></decl.function.returntype></decl.function.method.instance>",
@@ -5767,7 +5767,7 @@
         key.name: "subtracting(_:)",
         key.usr: "s:FEsPs10SetAlgebra11subtractingFxx::SYNTHESIZED::c:@E@FooRuncingOptions",
         key.original_usr: "s:FEsPs10SetAlgebra11subtractingFxx",
-        key.doc.full_as_xml: "<Function><Name>subtracting(_:)</Name><USR>s:FEsPs10SetAlgebra11subtractingFxx</USR><Declaration>func subtracting(_ other: Self) -&gt; Self</Declaration><Abstract><Para>Returns a new set containing the elements of this set that do not occur in the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A new set.</Para></ResultDiscussion><Discussion><Para>For example:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let neighbors: Set = [\"Bethany\", \"Eric\", \"Forlani\", \"Greta\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let nonNeighbors = employees.subtract(neighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(nonNeighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"[\"Diana\", \"Chris\", \"Alicia\"]\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+        key.doc.full_as_xml: "<Function><Name>subtracting(_:)</Name><USR>s:FEsPs10SetAlgebra11subtractingFxx</USR><Declaration>func subtracting(_ other: Self) -&gt; Self</Declaration><Abstract><Para>Returns a new set containing the elements of this set that do not occur in the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para>A new set.</Para></ResultDiscussion><Discussion><Para>In the following example, the <codeVoice>nonNeighbors</codeVoice> set is made up of the elements of the <codeVoice>employees</codeVoice> set that are not elements of <codeVoice>neighbors</codeVoice>:</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let neighbors: Set = [\"Bethany\", \"Eric\", \"Forlani\", \"Greta\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let nonNeighbors = employees.subtract(neighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(nonNeighbors)]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"[\"Diana\", \"Chris\", \"Alicia\"]\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
         key.offset: 2918,
         key.length: 65,
         key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>subtracting</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>_</decl.var.parameter.argument_label> <decl.var.parameter.name>other</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -&gt; <decl.function.returntype><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.function.returntype></decl.function.method.instance>",
@@ -5796,7 +5796,7 @@
         key.name: "isStrictSuperset(of:)",
         key.usr: "s:FEsPs10SetAlgebra16isStrictSupersetFT2ofx_Sb::SYNTHESIZED::c:@E@FooRuncingOptions",
         key.original_usr: "s:FEsPs10SetAlgebra16isStrictSupersetFT2ofx_Sb",
-        key.doc.full_as_xml: "<Function><Name>isStrictSuperset(of:)</Name><USR>s:FEsPs10SetAlgebra16isStrictSupersetFT2ofx_Sb</USR><Declaration>func isStrictSuperset(of other: Self) -&gt; Bool</Declaration><Abstract><Para>Returns a Boolean value that indicates whether this set is a strict superset of the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>true</codeVoice> if the set is a strict superset of <codeVoice>other</codeVoice>; otherwise, <codeVoice>false</codeVoice>.</Para></ResultDiscussion><Discussion><Para>Set <emphasis>A</emphasis> is a strict superset of another set <emphasis>B</emphasis> if every member of <emphasis>B</emphasis> is also a member of <emphasis>A</emphasis> and <emphasis>A</emphasis> contains at least one element that is <emphasis>not</emphasis> a member of <emphasis>B</emphasis>.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let attendees: Set = [\"Alicia\", \"Bethany\", \"Diana\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isStrictSuperset(of: attendees))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isStrictSuperset(of: employees))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"false\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
+        key.doc.full_as_xml: "<Function><Name>isStrictSuperset(of:)</Name><USR>s:FEsPs10SetAlgebra16isStrictSupersetFT2ofx_Sb</USR><Declaration>func isStrictSuperset(of other: Self) -&gt; Bool</Declaration><Abstract><Para>Returns a Boolean value that indicates whether this set is a strict superset of the given set.</Para></Abstract><Parameters><Parameter><Name>other</Name><Direction isExplicit=\"0\">in</Direction><Discussion><Para>A set of the same type as the current set.</Para></Discussion></Parameter></Parameters><ResultDiscussion><Para><codeVoice>true</codeVoice> if the set is a strict superset of <codeVoice>other</codeVoice>; otherwise, <codeVoice>false</codeVoice>.</Para></ResultDiscussion><Discussion><Para>Set <emphasis>A</emphasis> is a strict superset of another set <emphasis>B</emphasis> if every member of <emphasis>B</emphasis> is also a member of <emphasis>A</emphasis> and <emphasis>A</emphasis> contains at least one element that is <emphasis>not</emphasis> a member of <emphasis>B</emphasis>.</Para><CodeListing language=\"swift\"><zCodeLineNumbered><![CDATA[let employees: Set = [\"Alicia\", \"Bethany\", \"Chris\", \"Diana\", \"Eric\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[let attendees: Set = [\"Alicia\", \"Bethany\", \"Diana\"]]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isStrictSuperset(of: attendees))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"true\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// A set is never a strict superset of itself:]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[print(employees.isStrictSuperset(of: employees))]]></zCodeLineNumbered><zCodeLineNumbered><![CDATA[// Prints \"false\"]]></zCodeLineNumbered><zCodeLineNumbered></zCodeLineNumbered></CodeListing></Discussion></Function>",
         key.offset: 3020,
         key.length: 58,
         key.fully_annotated_decl: "<decl.function.method.instance><syntaxtype.keyword>func</syntaxtype.keyword> <decl.name>isStrictSuperset</decl.name>(<decl.var.parameter><decl.var.parameter.argument_label>of</decl.var.parameter.argument_label> <decl.var.parameter.name>other</decl.var.parameter.name>: <decl.var.parameter.type><ref.struct usr=\"c:@E@FooRuncingOptions\">FooRuncingOptions</ref.struct></decl.var.parameter.type></decl.var.parameter>) -&gt; <decl.function.returntype><ref.struct usr=\"s:Sb\">Bool</ref.struct></decl.function.returntype></decl.function.method.instance>",
diff --git a/test/decl/import/import.swift b/test/decl/import/import.swift
index aceeeb8..03f0edc 100644
--- a/test/decl/import/import.swift
+++ b/test/decl/import/import.swift
@@ -41,7 +41,7 @@
 import func Swift.min
 
 import var x // expected-error {{expected module name}}
-import struct Swift.nonexistent // expected-error {{no such decl in module}}
+import struct Swift.nonexistent // expected-error {{struct 'nonexistent' does not exist in module 'Swift'}}
 
 import Swift.import.abc // expected-error {{expected identifier in import declaration}}
 // expected-error @-1 {{keyword 'import' cannot be used as an identifier here}}
diff --git a/test/lit.cfg b/test/lit.cfg
index a6a34af..2e1ed5f 100644
--- a/test/lit.cfg
+++ b/test/lit.cfg
@@ -691,17 +691,30 @@
         "%s clang++ %s" %
         (xcrun_prefix, config.target_cc_options))
 
-elif run_os == 'linux-gnu' or run_os == 'linux-gnueabihf' or run_os == 'freebsd':
-    # Linux/FreeBSD
-    if run_os == 'freebsd':
+elif run_os in ['linux-gnu', 'linux-gnueabihf', 'freebsd', 'windows-cygnus', 'windows-gnu']:
+    # Linux/FreeBSD/Cygwin
+    if run_os == 'windows-cygnus':
+      lit_config.note("Testing Cygwin " + config.variant_triple)
+      config.target_object_format = "coff"
+      config.target_dylib_extension = "dll"
+      config.target_sdk_name = "cygwin"
+    elif run_os == 'windows-gnu':
+      lit_config.note("Testing MinGW " + config.variant_triple)
+      config.target_object_format = "coff"
+      config.target_dylib_extension = "dll"
+      config.target_sdk_name = "mingw"
+    elif run_os == 'freebsd':
       lit_config.note("Testing FreeBSD " + config.variant_triple)
+      config.target_object_format = "elf"
+      config.target_dylib_extension = "so"
+      config.target_sdk_name = "freebsd"
     else:
       lit_config.note("Testing Linux " + config.variant_triple)
-    config.target_object_format = "elf"
-    config.target_dylib_extension = "so"
+      config.target_object_format = "elf"
+      config.target_dylib_extension = "so"
+      config.target_sdk_name = "linux"
     config.target_runtime = "native"
     config.target_swift_autolink_extract = inferSwiftBinary("swift-autolink-extract")
-    config.target_sdk_name = "freebsd" if run_os == "freebsd" else "linux"
     config.target_build_swift = (
         '%s -target %s %s %s %s %s'
         % (config.swiftc, config.variant_triple, resource_dir_opt, mcp_opt,
diff --git a/tools/driver/autolink_extract_main.cpp b/tools/driver/autolink_extract_main.cpp
index 949aca3..64cca89 100644
--- a/tools/driver/autolink_extract_main.cpp
+++ b/tools/driver/autolink_extract_main.cpp
@@ -31,6 +31,7 @@
 #include "llvm/Option/Option.h"
 #include "llvm/Object/Archive.h"
 #include "llvm/Object/ObjectFile.h"
+#include "llvm/Object/COFF.h"
 #include "llvm/Object/ELFObjectFile.h"
 
 using namespace swift;
@@ -106,32 +107,44 @@
   }
 };
 
-// Look inside the binary 'Bin' and append any linker flags found in its
-// ".swift1_autolink_entries" section to 'LinkerFlags'. If 'Bin' is an archive,
-// recursively look inside all children within the archive. Return 'true' if
-// there was an error, and 'false' otherwise.
+/// Look inside the object file 'ObjectFile' and append any linker flags found in
+/// its ".swift1_autolink_entries" section to 'LinkerFlags'.
+static void
+extractLinkerFlagsFromObjectFile(const llvm::object::ObjectFile *ObjectFile,
+                                 std::vector<std::string> &LinkerFlags) {
+  // Search for the section we hold autolink entries in
+  for (auto &Section : ObjectFile->sections()) {
+    llvm::StringRef SectionName;
+    Section.getName(SectionName);
+    if (SectionName == ".swift1_autolink_entries") {
+      llvm::StringRef SectionData;
+      Section.getContents(SectionData);
+
+      // entries are null-terminated, so extract them and push them into
+      // the set.
+      llvm::SmallVector<llvm::StringRef, 4> SplitFlags;
+      SectionData.split(SplitFlags, llvm::StringRef("\0", 1), -1,
+                        /*KeepEmpty=*/false);
+      for (const auto &Flag : SplitFlags)
+        LinkerFlags.push_back(Flag);
+    }
+  }
+}
+
+/// Look inside the binary 'Bin' and append any linker flags found in its
+/// ".swift1_autolink_entries" section to 'LinkerFlags'. If 'Bin' is an archive,
+/// recursively look inside all children within the archive. Return 'true' if
+/// there was an error, and 'false' otherwise.
 static bool extractLinkerFlags(const llvm::object::Binary *Bin,
                                CompilerInstance &Instance,
                                StringRef BinaryFileName,
                                std::vector<std::string> &LinkerFlags) {
   if (auto *ObjectFile = llvm::dyn_cast<llvm::object::ELFObjectFileBase>(Bin)) {
-    // Search for the section we hold autolink entries in
-    for (auto &Section : ObjectFile->sections()) {
-      llvm::StringRef SectionName;
-      Section.getName(SectionName);
-      if (SectionName == ".swift1_autolink_entries") {
-        llvm::StringRef SectionData;
-        Section.getContents(SectionData);
-
-        // entries are null-terminated, so extract them and push them into
-        // the set.
-        llvm::SmallVector<llvm::StringRef, 4> SplitFlags;
-        SectionData.split(SplitFlags, llvm::StringRef("\0", 1), -1,
-                          /*KeepEmpty=*/false);
-        for (const auto &Flag : SplitFlags)
-          LinkerFlags.push_back(Flag);
-      }
-    }
+    extractLinkerFlagsFromObjectFile(ObjectFile, LinkerFlags);
+    return false;
+  } else if (auto *ObjectFile =
+                 llvm::dyn_cast<llvm::object::COFFObjectFile>(Bin)) {
+    extractLinkerFlagsFromObjectFile(ObjectFile, LinkerFlags);
     return false;
   } else if (auto *Archive = llvm::dyn_cast<llvm::object::Archive>(Bin)) {
     for (const auto &Child : Archive->children()) {
diff --git a/utils/SwiftBuildSupport.py b/utils/SwiftBuildSupport.py
index f7e6a04..5a19524 100644
--- a/utils/SwiftBuildSupport.py
+++ b/utils/SwiftBuildSupport.py
@@ -24,7 +24,6 @@
 
 # E402 means module level import not at top of file
 from swift_build_support import diagnostics  # noqa (E402)
-from swift_build_support import shell  # noqa (E402)
 
 
 HOME = os.environ.get("HOME", "/")
diff --git a/utils/swift_build_support/tests/products/test_swift.py b/utils/swift_build_support/tests/products/test_swift.py
index be9dd47..7bd9757 100644
--- a/utils/swift_build_support/tests/products/test_swift.py
+++ b/utils/swift_build_support/tests/products/test_swift.py
@@ -11,7 +11,6 @@
 
 import argparse
 import os
-import platform
 import shutil
 import sys
 import tempfile
@@ -24,7 +23,6 @@
     from io import StringIO
 
 from swift_build_support import shell
-from swift_build_support import xcrun
 from swift_build_support.products import Swift
 from swift_build_support.toolchain import host_toolchain
 from swift_build_support.workspace import Workspace
diff --git a/validation-test/StdlibUnittest/Assertions.swift.gyb b/validation-test/StdlibUnittest/Assertions.swift.gyb
index e66b9e4..ea73f2d 100644
--- a/validation-test/StdlibUnittest/Assertions.swift.gyb
+++ b/validation-test/StdlibUnittest/Assertions.swift.gyb
@@ -219,5 +219,36 @@
   }
 }
 
+AssertionsTestSuite.test("expectEqual<T : Equatable, U : Equatable, V : Equatable, W : Equatable>") {
+  let _0 = MinimalEquatableValue(0)
+  let _1 = MinimalEquatableValue(1)
+
+  for a in [_0, _1] {
+    for b in [_0, _1] {
+      for c in [_0, _1] {
+        for d in [_0, _1] {
+          for e in [_0, _1] {
+            for f in [_0, _1] {
+              for g in [_0, _1] {
+                for h in [_0, _1] {
+                  let lhs = (a, b, c, d)
+                  let rhs = (e, f, g, h)
+                  if lhs == rhs {
+                    expectEqual(lhs, rhs)
+                  } else {
+                    expectFailure {
+                      expectEqual(lhs, rhs)
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
 runAllTests()
 
diff --git a/validation-test/compiler_crashers/28385-swift-constraints-constraintgraph-addconstraint.swift b/validation-test/compiler_crashers/28385-swift-constraints-constraintgraph-addconstraint.swift
new file mode 100644
index 0000000..b1e489b
--- /dev/null
+++ b/validation-test/compiler_crashers/28385-swift-constraints-constraintgraph-addconstraint.swift
@@ -0,0 +1,10 @@
+// This source file is part of the Swift.org open source project
+// Copyright (c) 2014 - 2016 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+
+// RUN: not --crash %target-swift-frontend %s -parse
+// REQUIRES: asserts
+assert((n:String{
diff --git a/validation-test/compiler_crashers/28386-swift-typebase-getdesugaredtype.swift b/validation-test/compiler_crashers/28386-swift-typebase-getdesugaredtype.swift
new file mode 100644
index 0000000..877522d
--- /dev/null
+++ b/validation-test/compiler_crashers/28386-swift-typebase-getdesugaredtype.swift
@@ -0,0 +1,12 @@
+// This source file is part of the Swift.org open source project
+// Copyright (c) 2014 - 2016 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+
+// RUN: not --crash %target-swift-frontend %s -parse
+struct A{init(){let:A
+class B:A
+class A:B{
+init()
diff --git a/validation-test/compiler_crashers/28387-swift-typebase-gatherallsubstitutions.swift b/validation-test/compiler_crashers/28387-swift-typebase-gatherallsubstitutions.swift
new file mode 100644
index 0000000..b766f71
--- /dev/null
+++ b/validation-test/compiler_crashers/28387-swift-typebase-gatherallsubstitutions.swift
@@ -0,0 +1,13 @@
+// This source file is part of the Swift.org open source project
+// Copyright (c) 2014 - 2016 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+
+// RUN: not --crash %target-swift-frontend %s -parse
+protocol a{typealias B<>:a{}typealias d)class B<T>:a{
+struct B<T>:a
+protocol c{
+}
+func c:d
diff --git a/validation-test/compiler_crashers_2_fixed/0022-rdar21625478.swift b/validation-test/compiler_crashers_2_fixed/0022-rdar21625478.swift
index 7feed32..54eb70c 100644
--- a/validation-test/compiler_crashers_2_fixed/0022-rdar21625478.swift
+++ b/validation-test/compiler_crashers_2_fixed/0022-rdar21625478.swift
@@ -35,8 +35,8 @@
     _ preprocess: (Self) -> R
   ) -> R?
 
-  func _copyToNativeArrayBuffer()
-    -> _ContiguousArrayBuffer<Iterator.Element>
+  func _copyToContiguousArray()
+    -> ContiguousArray<Iterator.Element>
 
   func _copyContents(
     initializing ptr: UnsafeMutablePointer<Iterator.Element>
@@ -71,8 +71,8 @@
     return nil
   }
 
-  public func _copyToNativeArrayBuffer()
-    -> _ContiguousArrayBuffer<Iterator.Element> {
+  public func _copyToContiguousArray()
+    -> ContiguousArray<Iterator.Element> {
     fatalError()
   }
 
@@ -224,7 +224,7 @@
   public static var filter = TypeIndexed(0)
   public static var _customContainsEquatableElement = TypeIndexed(0)
   public static var _preprocessingPass = TypeIndexed(0)
-  public static var _copyToNativeArrayBuffer = TypeIndexed(0)
+  public static var _copyToContiguousArray = TypeIndexed(0)
   public static var _copyContents = TypeIndexed(0)
 }
 
@@ -281,10 +281,10 @@
 
   /// Create a native array buffer containing the elements of `self`,
   /// in the same order.
-  public func _copyToNativeArrayBuffer()
-    -> _ContiguousArrayBuffer<Base.Iterator.Element> {
-    Log._copyToNativeArrayBuffer[selfType] += 1
-    return base._copyToNativeArrayBuffer()
+  public func _copyToContiguousArray()
+    -> ContiguousArray<Base.Iterator.Element> {
+    Log._copyToContiguousArray[selfType] += 1
+    return base._copyToContiguousArray()
   }
 
   /// Copy a Sequence into an array.
diff --git a/validation-test/stdlib/ArrayNew.swift.gyb b/validation-test/stdlib/ArrayNew.swift.gyb
index 542f6bd..e5b6bcc 100644
--- a/validation-test/stdlib/ArrayNew.swift.gyb
+++ b/validation-test/stdlib/ArrayNew.swift.gyb
@@ -19,23 +19,14 @@
 all_array_types = ['ContiguousArray', 'ArraySlice', 'Array']
 }%
 
-extension Array {
-  var identity: UnsafeRawPointer {
-    return self._buffer.identity
+%for Self in all_array_types:
+extension ${Self} {
+  typealias _BufferID = UnsafeRawPointer?
+  var _bufferID: _BufferID {
+    return unsafeBitCast(_owner, to: _BufferID.self)
   }
 }
-
-extension ArraySlice {
-  var identity: UnsafeRawPointer {
-    return self._buffer.identity
-  }
-}
-
-extension ContiguousArray {
-  var identity: UnsafeRawPointer {
-    return self._buffer.identity
-  }
-}
+%end
 
 var ArrayTestSuite = TestSuite("Array")
 
@@ -64,21 +55,21 @@
     ${element_type}(40), ${element_type}(50), ${element_type}(60),
     ${element_type}(70)
   ]]
-  let identityOuter = a.identity
-  var identityInner = a[0].identity
+  let identityOuter = a._bufferID
+  var identityInner = a[0]._bufferID
 
   func checkIdentity(_ stackTrace: SourceLocStack) {
 %     if element_type == 'TestValueTy':
     // Does not reallocate storage because we changed a property based on a
     // reference; array storage was not changed.  Writeback of the inner array
     // does not happen.
-    expectEqual(identityOuter, a.identity, stackTrace: stackTrace)
-    expectEqual(identityInner, a[0].identity, stackTrace: stackTrace)
+    expectEqual(identityOuter, a._bufferID, stackTrace: stackTrace)
+    expectEqual(identityInner, a[0]._bufferID, stackTrace: stackTrace)
 %     else:
-    expectEqual(identityOuter, a.identity, stackTrace: stackTrace)
+    expectEqual(identityOuter, a._bufferID, stackTrace: stackTrace)
 
     // Should not reallocate storage.
-    expectEqual(identityInner, a[0].identity, stackTrace: stackTrace)
+    expectEqual(identityInner, a[0]._bufferID, stackTrace: stackTrace)
 %     end
   }
 
@@ -134,23 +125,23 @@
     ${element_type}(40), ${element_type}(50), ${element_type}(60),
     ${element_type}(70), ${element_type}(80), ${element_type}(90),
   ]]
-  let identityOuter = a.identity
-  var identityInner = a[0].identity
+  let identityOuter = a._bufferID
+  var identityInner = a[0]._bufferID
 
   func checkIdentity(_ stackTrace: SourceLocStack) {
 %     if element_type == 'TestValueTy':
     // Does not reallocate storage because we changed a property based on a
     // reference; array storage was not changed.
-    expectEqual(identityOuter, a.identity, stackTrace: stackTrace)
-    expectEqual(identityInner, a[0].identity, stackTrace: stackTrace)
+    expectEqual(identityOuter, a._bufferID, stackTrace: stackTrace)
+    expectEqual(identityInner, a[0]._bufferID, stackTrace: stackTrace)
 %     else:
-    expectEqual(identityOuter, a.identity, stackTrace: stackTrace)
+    expectEqual(identityOuter, a._bufferID, stackTrace: stackTrace)
     // Writeback happens in subscript(Range<Int>), but array notices that the new
     // value did not change.
     // Another writeback happens in Array.subscript(Int), but this is not what we
     // want.
-    expectNotEqual(identityInner, a[0].identity, stackTrace: stackTrace)
-    identityInner = a[0].identity
+    expectNotEqual(identityInner, a[0]._bufferID, stackTrace: stackTrace)
+    identityInner = a[0]._bufferID
 %     end
   }
 
@@ -158,9 +149,9 @@
   a[0..<1][0][0] = ${element_type}(1010)
 
   // Reallocates storage because of the writeback in Array.subscript(Int).
-  expectEqual(identityOuter, a.identity)
-  expectNotEqual(identityInner, a[0].identity)
-  identityInner = a[0].identity
+  expectEqual(identityOuter, a._bufferID)
+  expectNotEqual(identityInner, a[0]._bufferID)
+  identityInner = a[0]._bufferID
 
   a[0..<1][0][1].value = 1020
 
@@ -195,9 +186,9 @@
   // Reallocates storage because of the writeback in Array.subscript(Int)
   // (writeback is being requested for the array element even though it is not
   // needed).
-  expectEqual(identityOuter, a.identity)
-  expectNotEqual(identityInner, a[0].identity)
-  identityInner = a[0].identity
+  expectEqual(identityOuter, a._bufferID)
+  expectNotEqual(identityInner, a[0]._bufferID)
+  identityInner = a[0]._bufferID
 
   withInoutT(&a[0..<1][0][6].value) {
     (x: inout Int) in
diff --git a/validation-test/stdlib/Arrays.swift.gyb b/validation-test/stdlib/Arrays.swift.gyb
index 6c56286..def3a35 100644
--- a/validation-test/stdlib/Arrays.swift.gyb
+++ b/validation-test/stdlib/Arrays.swift.gyb
@@ -73,23 +73,14 @@
 all_array_types = ['ContiguousArray', 'ArraySlice', 'Array']
 }%
 
-extension Array {
-  var identity: UnsafeRawPointer {
-    return self._buffer.identity
+%for Self in all_array_types:
+extension ${Self} {
+  typealias _BufferID = UnsafeRawPointer?
+  var _bufferID: _BufferID {
+    return unsafeBitCast(_owner, to: _BufferID.self)
   }
 }
-
-extension ArraySlice {
-  var identity: UnsafeRawPointer {
-    return self._buffer.identity
-  }
-}
-
-extension ContiguousArray {
-  var identity: UnsafeRawPointer {
-    return self._buffer.identity
-  }
-}
+%end
 
 var ArrayTestSuite = TestSuite("Array")
 
@@ -246,10 +237,10 @@
   let arr0 = ${array_type}<Int>()
   let arr1 = ${array_type}<LifetimeTracked>(repeating: LifetimeTracked(0), count: 0)
   // Empty arrays all use the same buffer
-  expectEqual(arr0._buffer.identity, arr1._buffer.identity)
+  expectEqual(arr0._bufferID, arr1._bufferID)
 
   let arr2: ${array_type}<LifetimeTracked> = []
-  let emptyLiteralsShareBuffer = arr0._buffer.identity == arr2._buffer.identity
+  let emptyLiteralsShareBuffer = arr0._bufferID == arr2._bufferID
   expectTrue(emptyLiteralsShareBuffer)
 }
 
diff --git a/validation-test/stdlib/NewArray.swift.gyb b/validation-test/stdlib/NewArray.swift.gyb
index 1e3a19a..80e33c2 100644
--- a/validation-test/stdlib/NewArray.swift.gyb
+++ b/validation-test/stdlib/NewArray.swift.gyb
@@ -32,16 +32,39 @@
   print("]")
 }
 
-typealias BufferID = UnsafeRawPointer?
+typealias _BufferID = UnsafeRawPointer?
 
-func bufferID<T : _ArrayProtocol>(_ x: T) -> BufferID {
-  return x._buffer.identity
+protocol MyArrayProtocol
+  : RandomAccessCollection,
+    RangeReplaceableCollection,
+    MutableCollection,
+    ArrayLiteralConvertible {
+
+  associatedtype Iterator : IteratorProtocol
+
+  var _owner: AnyObject? { get }
+
+  var capacity: Int { get }
+
+  func += <
+    S : Sequence
+    where
+    S.Iterator.Element == Iterator.Element
+  >(lhs: inout Self, rhs: S)
 }
+extension MyArrayProtocol {
+  var _bufferID: _BufferID {
+    return unsafeBitCast(_owner, to: _BufferID.self)
+  }
+}
+extension Array : MyArrayProtocol {}
+extension ArraySlice : MyArrayProtocol {}
+extension ContiguousArray : MyArrayProtocol {}
 
-func checkReallocation<T : _ArrayProtocol>(
-  _ x: T, _ lastBuffer: BufferID, _ reallocationExpected: Bool
-) -> BufferID {
-  let currentBuffer = bufferID(x)
+func checkReallocation<T : MyArrayProtocol>(
+  _ x: T, _ lastBuffer: _BufferID, _ reallocationExpected: Bool
+) -> _BufferID {
+  let currentBuffer = x._bufferID
   if (currentBuffer != lastBuffer) != reallocationExpected {
     let message = reallocationExpected ? "lack of" : ""
     print("unexpected \(message) reallocation")
@@ -62,13 +85,12 @@
 }
 
 func test<
-  T : _ArrayProtocol
+  T : MyArrayProtocol
   where
-  T.Iterator.Element == T._Buffer.Element,
-  T._Buffer.Element == T.Element,
-  T.Element == LifetimeTracked,
+  T.Iterator.Element == LifetimeTracked,
+  T.Iterator.Element == T.Element,
   T.Index == Int,
-  T : RandomAccessCollection
+  T.IndexDistance == Int
 >(_: T.Type, _ label: String) {
   print("test: \(label)...", terminator: "")
 
@@ -85,7 +107,7 @@
   x.reserveCapacity(x.count + 2)
   checkEqual(x, LifetimeTracked(1)...LifetimeTracked(5), true)
   
-  let bufferId0 = bufferID(x)
+  let bufferId0 = x._bufferID
 
   // Append a range of integers
   x += LifetimeTracked(0)..<LifetimeTracked(2)
@@ -113,9 +135,9 @@
     // has shown that using 1.5, the other popular growth factor,
     // slows things down.
     for _ in a.count..<(a.capacity * 4) {
-      let oldId = bufferID(a)
+      let oldId = a._bufferID
       growBy1(&a)
-      if oldId != bufferID(a) {
+      if oldId != a._bufferID {
         reallocations += 1
       }
     }
@@ -156,29 +178,29 @@
   // CHECK: == AsArray == 
   
   let x = ContiguousArray(w)
-  print(bufferID(w) == bufferID(x))
+  print(w._bufferID == x._bufferID)
   // CHECK-NEXT: true
   
   let y = Array(x)
-  print(bufferID(x) == bufferID(y))
+  print(x._bufferID == y._bufferID)
   // CHECK-NEXT: true
 
   // Because of their indirection, arrays of classes can share
   // buffers.  
   let y1 = Array(y)
-  print(bufferID(y1) == bufferID(y))
+  print(y1._bufferID == y._bufferID)
   // CHECK-NEXT: true
   
   let z = ArraySlice(y)
-  print(bufferID(y) == bufferID(z))
+  print(y._bufferID == z._bufferID)
   // CHECK-NEXT: true
 
   w = ContiguousArray(z)
-  print(bufferID(w) == bufferID(z))
+  print(w._bufferID == z._bufferID)
   // CHECK-NEXT: true
 
   let zz = y[0..<2]
-  print(bufferID(zz))
+  print(zz._bufferID)
   // CHECK-NEXT: 0x
 }
 testAsArray()
diff --git a/validation-test/stdlib/StringViews.swift b/validation-test/stdlib/StringViews.swift
index ef0cc6a..3f8da63 100644
--- a/validation-test/stdlib/StringViews.swift
+++ b/validation-test/stdlib/StringViews.swift
@@ -14,6 +14,7 @@
 
 import Swift
 import StdlibUnittest
+import StdlibCollectionUnittest
 
 #if _runtime(_ObjC)
 // FIXME: Foundation leaks through StdlibUnittest.  It adds some conformances
@@ -740,5 +741,123 @@
   }
 }
 
+struct StringViewTest {
+  var string: String
+  var utf8: [UInt8]
+  var utf16: [UInt16]
+  var unicodeScalars: [UnicodeScalar]
+
+  init(string: String, utf8: [UInt8], utf16: [UInt16], utf32: [UInt32]) {
+    self.string = string
+    self.utf8 = utf8
+    self.utf16 = utf16
+    self.unicodeScalars = utf32.map { UnicodeScalar($0)! }
+  }
+}
+
+var stringViewTests: [StringViewTest] = [
+  StringViewTest(
+    string: "",
+    utf8: [],
+    utf16: [],
+    utf32: []),
+  StringViewTest(
+    string: "\u{0000}",
+    utf8: [0x00],
+    utf16: [0x00],
+    utf32: [0x00]),
+  StringViewTest(
+    string: "a",
+    utf8: [0x61],
+    utf16: [0x61],
+    utf32: [0x61]),
+  StringViewTest(
+    string: "aa",
+    utf8: [0x61, 0x61],
+    utf16: [0x61, 0x61],
+    utf32: [0x61, 0x61]),
+  StringViewTest(
+    string: "ab",
+    utf8: [0x61, 0x62],
+    utf16: [0x61, 0x62],
+    utf32: [0x61, 0x62]),
+  StringViewTest(
+    string: "abc",
+    utf8: [0x61, 0x62, 0x63],
+    utf16: [0x61, 0x62, 0x63],
+    utf32: [0x61, 0x62, 0x63]),
+  StringViewTest(
+    string: "\u{007f}",
+    utf8: [0x7f],
+    utf16: [0x7f],
+    utf32: [0x7f]),
+  StringViewTest(
+    string: "\u{0430}",
+    utf8: [0xd0, 0xb0],
+    utf16: [0x0430],
+    utf32: [0x0430]),
+  StringViewTest(
+    string: "\u{0430}\u{0431}\u{0432}",
+    utf8: [0xd0, 0xb0, 0xd0, 0xb1, 0xd0, 0xb2],
+    utf16: [0x0430, 0x0431, 0x0432],
+    utf32: [0x0430, 0x0431, 0x0432]),
+  StringViewTest(
+    string: "\u{1f425}",
+    utf8: [0xf0, 0x9f, 0x90, 0xa5],
+    utf16: [0xd83d, 0xdc25],
+    utf32: [0x1f425]),
+]
+
+#if _runtime(_ObjC)
+tests.test("String.UTF16View.Index/Strideable")
+  .forEach(in: stringViewTests) {
+  test in
+
+  func allIndices<C : Collection>(of c: C) -> [C.Index]
+  where C.Indices.Iterator.Element == C.Index
+  {
+    var result = Array(c.indices)
+    result.append(c.endIndex)
+    return result
+  }
+
+  checkStrideable(
+    instances: allIndices(of: test.string.utf16),
+    distances: Array(0..<test.string.utf16.count),
+    distanceOracle: { $1 - $0 })
+}
+#endif
+
+tests.test("String.UTF8View/Collection")
+  .forEach(in: stringViewTests) {
+  test in
+
+  // FIXME(ABI): should be `checkBidirectionalCollection`.
+  checkForwardCollection(test.utf8, test.string.utf8) { $0 == $1 }
+}
+
+#if _runtime(_Native)
+tests.test("String.UTF16View/BidirectionalCollection")
+  .forEach(in: stringViewTests) {
+  test in
+
+  checkBidirectionalCollection(test.utf16, test.string.utf16) { $0 == $1 }
+}
+#else
+tests.test("String.UTF16View/RandomAccessCollection")
+  .forEach(in: stringViewTests) {
+  test in
+
+  checkRandomAccessCollection(test.utf16, test.string.utf16) { $0 == $1 }
+}
+#endif
+
+tests.test("String.UTF32View/BidirectionalCollection")
+  .forEach(in: stringViewTests) {
+  test in
+
+  checkBidirectionalCollection(
+    test.unicodeScalars, test.string.unicodeScalars) { $0 == $1 }
+}
 
 runAllTests()