[stdlib] Various documentation revisions and fixes

- Revisions to unsafeDowncast and withVaList
- Fix the Int64/UInt64 discussion
- Buffer pointer revisions
- Fix Optional example to use new integer methods
- Revise and correct some UnsafeRawBufferPointer docs
- Fix symmetricDifference examples
- Fix wording in FloatingPoint.nextDown
- Update ImplicitlyUnwrappedOptional
- Clarify elementsEqual
- Minor integer doc fixes
- Comment for _AppendKeyPath
- Clarification re collection indices
- Revise RangeExpression.relative(to:)
- Codable revisions

Author: natecook1000

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/Codable.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/Collection.swift

@@ -1005,7 +1005,7 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable {
 
   /// The greatest representable value that compares less than this value.
   ///
-  /// For any finite value `x`, `x.nextDown` is greater than `x`. For `nan` or
+  /// For any finite value `x`, `x.nextDown` is less than `x`. For `nan` or
   /// `-infinity`, `x.nextDown` is `x` itself. The following special cases
   /// also apply:
   ///

stdlib/public/core/FloatingPoint.swift.gyb

@@ -1120,9 +1120,8 @@ public struct Set<Element : Hashable> :
   /// 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.
+  /// `employees`. In particular, the names `"Bethany"` and `"Eric"` are
+  /// removed from `employees` while the name `"Forlani"` is added.
   ///
   ///     var employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
   ///     let neighbors = ["Bethany", "Eric", "Forlani"]

stdlib/public/core/HashedCollections.swift.gyb

@@ -12,7 +12,15 @@
 
 /// An optional type that allows implicit member access.
 ///
-/// *Deprecated.*
+/// The `ImplicitlyUnwrappedOptional` type is deprecated. To create an optional
+/// value that is implicitly unwrapped, place an exclamation mark (`!`) after
+/// the type that you want to denote as optional.
+///
+///     // An implicitly unwrapped optional integer
+///     let guaranteedNumber: Int! = 6
+///
+///     // An optional integer
+///     let possibleNumber: Int? = 5
 @_fixed_layout
 public enum ImplicitlyUnwrappedOptional<Wrapped> : ExpressibleByNilLiteral {
   // The compiler has special knowledge of the existence of

stdlib/public/core/ImplicitlyUnwrappedOptional.swift

@@ -1335,6 +1335,9 @@ public protocol BinaryInteger :
   /// Creates an integer from the given floating-point value, rounding toward
   /// zero.
   ///
+  /// Any fractional part of the value passed as `source` is removed, rounding
+  /// the value toward zero.
+  ///
   ///     let x = Int(21.5)
   ///     // x == 21
   ///     let y = Int(-21.5)
@@ -1347,7 +1350,8 @@ public protocol BinaryInteger :
   ///     // Error: ...the result would be less than UInt.min
   ///
   /// - Parameter source: A floating-point value to convert to an integer.
-  ///   `source` must be representable in this type after rounding toward zero.
+  ///   `source` must be representable in this type after rounding toward
+  ///   zero.
   init<T : BinaryFloatingPoint>(_ source: T)
 
   /// Creates a new instance from the given integer.
@@ -2502,7 +2506,7 @@ extension SignedInteger where Self : FixedWidthInteger {
 %   z = 's' if signed else 'z'
 
 %   Article = 'An' if bits == 8 else 'A'
-%   if bits == word_bits:
+%   if self_type.is_word:
 /// ${'A ' if signed else 'An un'}signed integer value type.
 ///
 /// On 32-bit platforms, `${Self}` is the same size as `${Self}32`, and

stdlib/public/core/Integers.swift.gyb

@@ -1347,6 +1347,9 @@ func _projectKeyPathReferenceWritable<Root, Value>(
 // constrained by being overrides, and so that we can use exact-type constraints
 // on `Self` to prevent dynamically-typed methods from being inherited by
 // statically-typed key paths.
+
+/// This protocol is an implementation detail of key path expressions; do not
+/// use it directly.
 @_show_in_interface
 public protocol _AppendKeyPath {}
 

stdlib/public/core/KeyPath.swift

@@ -178,8 +178,8 @@ public enum Optional<Wrapped> : ExpressibleByNilLiteral {
   ///
   ///     let possibleNumber: Int? = Int("42")
   ///     let nonOverflowingSquare = possibleNumber.flatMap { x -> Int? in
-  ///         let (result, overflowed) = Int.multiplyWithOverflow(x, x)
-  ///         return overflowed ? nil : result
+  ///         let (result, overflowed) = x.multipliedReportingOverflow(by: x)
+  ///         return overflowed == .overflow ? nil : result
   ///     }
   ///     print(nonOverflowingSquare)
   ///     // Prints "Optional(1764)"

stdlib/public/core/Optional.swift

@@ -18,6 +18,39 @@ public protocol RangeExpression {
   /// Returns the range of indices within the given collection described by
   /// this range expression.
   ///
+  /// You can use the `relative(to:)` method to convert a range expression,
+  /// which could be missing one or both of its endpoints, into a concrete
+  /// range that is bounded on both sides. The following example uses this
+  /// method to convert a partial range up to `4` into a half-open range,
+  /// using an array instance to add the range's lower bound.
+  ///
+  ///     let numbers = [10, 20, 30, 40, 50, 60, 70]
+  ///     let upToFour = ..<4
+  ///
+  ///     let r1 = upToFour.relative(to: numbers)
+  ///     // r1 == 0..<4
+  ///
+  /// The `r1` range is bounded on the lower end by `0` because that is the
+  /// starting index of the `numbers` array. When the collection passed to
+  /// `relative(to:)` starts with a different index, that index is used as the
+  /// lower bound instead. The next example creates a slice of `numbers`
+  /// starting at index `2`, and then uses the slice with `relative(to:)` to
+  /// convert `upToFour` to a concrete range.
+  ///
+  ///     let numbersSuffix = numbers[2...]
+  ///     // numbersSuffix == [30, 40, 50, 60, 70]
+  ///
+  ///     let r2 = upToFour.relative(to: numbersSuffix)
+  ///     // r2 == 2..<4
+  ///
+  /// Use this method only if you need the concrete range it produces. To
+  /// access a slice of a collection using a range expression, use the
+  /// collection's generic subscript that uses a range expression as its
+  /// parameter.
+  ///
+  ///     let numbersPrefix = numbers[upToFour]
+  ///     // numbersPrefix == [10, 20, 30, 40]
+  ///
   /// - Parameter collection: The collection to evaluate this range expression
   ///   in relation to.
   /// - Returns: A range suitable for slicing `collection`. The returned range

stdlib/public/core/Range.swift.gyb

@@ -301,8 +301,8 @@ extension Sequence ${"" if preds else "where Element : Equatable"} {
 
 %   if preds:
   /// Returns a Boolean value indicating whether this sequence and another
-  /// sequence contain equivalent elements, using the given predicate as the
-  /// equivalence test.
+  /// sequence contain equivalent elements in the same order, using the given
+  /// predicate as the equivalence test.
   ///
   /// At least one of the sequences must be finite.
   ///

stdlib/public/core/SequenceAlgorithms.swift.gyb

@@ -276,15 +276,14 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   /// 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.
+  /// `employees`. In particular, the names `"Bethany"` and `"Eric"` are
+  /// removed from `employees` while the name `"Forlani"` is added.
   ///
-  ///     var employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
-  ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]
+  ///     var employees: Set = ["Alicia", "Bethany", "Diana", "Eric"]
+  ///     let neighbors: Set = ["Bethany", "Eric", "Forlani"]
   ///     employees.formSymmetricDifference(neighbors)
   ///     print(employees)
-  ///     // Prints "["Diana", "Chris", "Forlani", "Alicia", "Greta"]"
+  ///     // Prints "["Diana", "Forlani", "Alicia"]"
   ///
   /// - Parameter other: A set of the same type.
   mutating func formSymmetricDifference(_ other: Self)

stdlib/public/core/SetAlgebra.swift

@@ -306,15 +306,23 @@ public struct Unsafe${Mutable}BufferPointer<Element>
 %  if not Mutable:
   /// Creates a buffer over the same memory as the given buffer slice.
   ///
-  /// The new buffer will represent the same region of memory as the slice,
-  /// but it's indices will be rebased to zero. Given:
+  /// The new buffer represents the same region of memory as `slice`, but is
+  /// indexed starting at zero instead of sharing indices with the original
+  /// buffer. For example:
   ///
-  ///   let slice = buffer[n..<m]
-  ///   let rebased = UnsafeBufferPointer(rebasing: slice)
+  ///     let buffer = returnsABuffer()
+  ///     let n = 5
+  ///     let slice = buffer[n...]
+  ///     let rebased = UnsafeBufferPointer(rebasing: slice)
   ///
-  /// One may assume `rebased.startIndex == 0` and `rebased[0] == slice[n]`.
+  /// After rebasing `slice` as the `rebased` buffer, the following are true:
   ///
-  /// - Parameter slice: the raw buffer slice to rebase.
+  /// - `rebased.startIndex == 0`
+  /// - `rebased[0] == slice[n]`
+  /// - `rebased[0] == buffer[n]`
+  /// - `rebased.count == slice.count`
+  ///
+  /// - Parameter slice: The buffer slice to rebase.
   @_inlineable
   public init(rebasing slice: RandomAccessSlice<UnsafeBufferPointer<Element>>) {
     self.init(start: slice.base.baseAddress! + slice.startIndex,
@@ -324,15 +332,23 @@ public struct Unsafe${Mutable}BufferPointer<Element>
 
   /// Creates a buffer over the same memory as the given buffer slice.
   ///
-  /// The new buffer will represent the same region of memory as the slice,
-  /// but it's indices will be rebased to zero. Given:
+  /// The new buffer represents the same region of memory as `slice`, but is
+  /// indexed starting at zero instead of sharing indices with the original
+  /// buffer. For example:
+  ///
+  ///     let buffer = returnsABuffer()
+  ///     let n = 5
+  ///     let slice = buffer[n...]
+  ///     let rebased = Unsafe${Mutable}BufferPointer(rebasing: slice)
   ///
-  ///   let slice = buffer[n..<m]
-  ///   let rebased = UnsafeBufferPointer(rebasing: slice)
+  /// After rebasing `slice` as the `rebased` buffer, the following are true:
   ///
-  /// One may assume `rebased.startIndex == 0` and `rebased[0] == slice[n]`.
+  /// - `rebased.startIndex == 0`
+  /// - `rebased[0] == slice[n]`
+  /// - `rebased[0] == buffer[n]`
+  /// - `rebased.count == slice.count`
   ///
-  /// - Parameter slice: the buffer slice to rebase.
+  /// - Parameter slice: The buffer slice to rebase.
   @_inlineable
   public init(
     rebasing slice:
@@ -388,17 +404,26 @@ extension Unsafe${Mutable}BufferPointer : CustomDebugStringConvertible {
 
 
 extension UnsafeMutableBufferPointer {
-  /// Initializes memory in the buffer with the elements of `source`.
-  /// Returns an iterator to any elements of `source` that didn't fit in the 
-  /// buffer, and an index to the point in the buffer one past the last element
-  /// written (so `startIndex` if no elements written, `endIndex` if the buffer 
-  /// was completely filled).
+  /// Initializes the buffer's memory with the given elements.
+  ///
+  /// When calling the `initialize(from:)` method on a buffer `b`, the memory
+  /// referenced by `b` must be uninitialized or the `Element` type must be a
+  /// trivial type. After the call, the memory referenced by this buffer up
+  /// to, but not including, the returned index is initialized. The buffer
+  /// must contain sufficient memory to accommodate
+  /// `source.underestimatedCount`.
   ///
-  /// - Precondition: The memory in `self` is uninitialized. The buffer must
-  ///   contain sufficient uninitialized memory to accommodate `source.underestimatedCount`.
+  /// The returned index is the position of the element in the buffer one past
+  /// the last element written. If `source` contains no elements, the returned
+  /// index is equal to the buffer's `startIndex`. If `source` contains an
+  /// equal or greater number of elements than the buffer can hold, the
+  /// returned index is equal to the buffer's `endIndex`.
   ///
-  /// - Postcondition: The `Pointee`s at `self[startIndex..<returned index]` are
-  ///   initialized.
+  /// - Parameter source: A sequence of elements with which to initializer the
+  ///   buffer.
+  /// - Returns: An iterator to any elements of `source` that didn't fit in the
+  ///   buffer, and an index to the point in the buffer one past the last
+  ///   element written.
   @_inlineable
   public func initialize<S: Sequence>(from source: S) -> (S.Iterator, Index)
     where S.Element == Element {