[stdlib] Documentation revisions

stdlib/public/core/Builtin.swift

@@ -246,18 +246,26 @@ public func _unsafeReferenceCast<T, U>(_ x: T, to: U.Type) -> U {
   return Builtin.castReference(x)
 }
 
-/// - returns: `x as T`.
+/// Returns the given instance cast unconditionally to the specified type.
 ///
-/// - Precondition: `x is T`.  In particular, in -O builds, no test is
-///   performed to ensure that `x` actually has dynamic type `T`.
+/// The instance passed as `x` must be an instance of type `T`.
 ///
-/// - Warning: Trades safety for performance.  Use `unsafeDowncast`
-///   only when `x as! T` has proven to be a performance problem and you
-///   are confident that, always, `x is T`.  It is better than an
-///   `unsafeBitCast` because it's more restrictive, and because
-///   checking is still performed in debug builds.
+/// Use this function instead of `unsafeBitcast(_:to:)` because this function
+/// is more restrictive and still performs a check in debug builds. In -O
+/// builds, no test is performed to ensure that `x` actually has the dynamic
+/// type `T`.
+///
+/// - Warning: This function trades safety for performance. Use
+///   `unsafeDowncast(_:to:)` only when you are confident that `x is T` always
+///   evaluates to `true`, and only after `x as! T` has proven to be a
+///   performance problem.
+///
+/// - Parameters:
+///   - x: An instance to cast to type `T`.
+///   - type: The type `T` to which `x` is cast.
+/// - Returns: The instance `x`, cast to type `T`.
 @_transparent
-public func unsafeDowncast<T : AnyObject>(_ x: AnyObject, to: T.Type) -> T {
+public func unsafeDowncast<T : AnyObject>(_ x: AnyObject, to type: T.Type) -> T {
   _debugPrecondition(x is T, "invalid unsafeDowncast")
   return Builtin.castReference(x)
 }
@@ -337,7 +345,6 @@ func swift_class_getInstanceExtents(_ theClass: AnyClass)
 func swift_objc_class_unknownGetInstanceExtents(_ theClass: AnyClass)
   -> (negative: UInt, positive: UInt)
 
-/// - Returns: 
 @inline(__always)
 internal func _class_getInstancePositiveExtentSize(_ theClass: AnyClass) -> Int {
 #if _runtime(_ObjC)

stdlib/public/core/Collection.swift

@@ -445,18 +445,6 @@ public struct IndexingIterator<
 /// corresponding element. In the example above, `firstSpace` is used to
 /// extract the prefix that contains elements up to that index.
 ///
-/// You can pass only valid indices to collection operations. You can find a
-/// complete set of a collection's valid indices by starting with the
-/// collection's `startIndex` property and finding every successor up to, and
-/// including, the `endIndex` property. All other values of the `Index` type,
-/// such as the `startIndex` property of a different collection, are invalid
-/// indices for this collection.
-///
-/// Saved indices may become invalid as a result of mutating operations. For
-/// more information about index invalidation in mutable collections, see the
-/// reference for the `MutableCollection` and `RangeReplaceableCollection`
-/// protocols, as well as for the specific type you're using.
-///
 /// Accessing Individual Elements
 /// =============================
 ///
@@ -481,6 +469,18 @@ public struct IndexingIterator<
 ///     print(text.first)
 ///     // Prints "Optional("B")"
 ///
+/// You can pass only valid indices to collection operations. You can find a
+/// complete set of a collection's valid indices by starting with the
+/// collection's `startIndex` property and finding every successor up to, and
+/// including, the `endIndex` property. All other values of the `Index` type,
+/// such as the `startIndex` property of a different collection, are invalid
+/// indices for this collection.
+///
+/// Saved indices may become invalid as a result of mutating operations. For
+/// more information about index invalidation in mutable collections, see the
+/// reference for the `MutableCollection` and `RangeReplaceableCollection`
+/// protocols, as well as for the specific type you're using.
+///
 /// Accessing Slices of a Collection
 /// ================================
 ///

stdlib/public/core/CompilerProtocols.swift

@@ -673,30 +673,8 @@ public protocol ExpressibleByDictionaryLiteral {
 /// Conforming to the ExpressibleByStringInterpolation Protocol
 /// ===========================================================
 ///
-/// To use string interpolation to initialize instances of your custom type,
-/// implement the required initializers for `ExpressibleByStringInterpolation`
-/// conformance. String interpolation is a multiple-step initialization
-/// process. When you use string interpolation, the following steps occur:
-///
-/// 1. The string literal is broken into pieces. Each segment of the string
-///    literal before, between, and after any included expressions, along with
-///    the individual expressions themselves, are passed to the
-///    `init(stringInterpolationSegment:)` initializer.
-/// 2. The results of those calls are passed to the
-///    `init(stringInterpolation:)` initializer in the order in which they
-///    appear in the string literal.
-///
-/// In other words, initializing the `message` constant in the example above
-/// using string interpolation is equivalent to the following code:
-///
-///     let message = String(stringInterpolation:
-///           String(stringInterpolationSegment: "One cookie: $"),
-///           String(stringInterpolationSegment: price),
-///           String(stringInterpolationSegment: ", "),
-///           String(stringInterpolationSegment: number),
-///           String(stringInterpolationSegment: " cookies: $"),
-///           String(stringInterpolationSegment: price * number),
-///           String(stringInterpolationSegment: "."))
+/// The `ExpressibleByStringInterpolation` protocol is deprecated. Do not add
+/// new conformances to the protocol.
 @available(*, deprecated, message: "it will be replaced or redesigned in Swift 4.0.  Instead of conforming to 'ExpressibleByStringInterpolation', consider adding an 'init(_:String)'")
 public typealias ExpressibleByStringInterpolation = _ExpressibleByStringInterpolation
 public protocol _ExpressibleByStringInterpolation {