[stdlib] Various documentation fixes

- Fix incorrect type in Float(_:String) examples
- Expand discussions for ExpressibleBy_Literal protocols
- Add notes about non-escaping unsafe pointers from closures
- Add note about isEmpty to Collection.count discussions
- Describe imported `Bool` types
- Clean up some floating point discussions
- Provide some additional operator documentation
- Revise documentation for CVarArg functions
- Fix incorrect Set method parameter descriptions
- Clarify array bridging behavior
- Add collection subscript complexity notes

Author: natecook1000

stdlib/public/core/Arrays.swift.gyb

@@ -41,7 +41,7 @@ public struct _DependenceToken {}
 %{
 if True:
   contiguousCaveat = (
-    ' If no such storage exists, it is first created.' if Self == 'Array'
+    ' If no such storage exists, it is created.' if Self == 'Array'
     else '')
 
   if Self == 'ContiguousArray':
@@ -397,7 +397,7 @@ if True:
 /// Bridging Between Array and NSArray
 /// ==================================
 ///
-/// When you need to access APIs that expect data in an `NSArray` instance
+/// When you need to access APIs that require data in an `NSArray` instance
 /// instead of `Array`, use the type-cast operator (`as`) to bridge your
 /// instance. For bridging to be possible, the `Element` type of your array
 /// must be a class, an `@objc` protocol (a protocol imported from Objective-C
@@ -406,9 +406,9 @@ if True:
 ///
 /// 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
+/// `colors` array can be bridged to `NSArray` because the `colors` array's
+/// `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"]
@@ -425,14 +425,23 @@ if True:
 /// 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:)`
+/// When the destination array's element type is a class or an `@objc`
+/// protocol, 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.
+/// performance is unspecified. If `copy(with:)` returns the same array, 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.
+///
+/// When the destination array's element type is a nonclass type that bridges
+/// to a Foundation type, bridging from `NSArray` to `Array` performs a
+/// bridging copy of the elements to contiguous storage in O(*n*) time. For
+/// example, bridging from `NSArray` to `Array<Int>` performs such a copy. No
+/// further bridging is required when accessing elements of the `Array`
+/// instance.
 ///
 /// - Note: The `ContiguousArray` and `ArraySlice` types are not bridged;
 ///   instances of those types always have a contiguous block of memory as
@@ -1138,21 +1147,21 @@ extension ${Self} : RangeReplaceableCollection, _ArrayProtocol {
   /// The total number of elements that the array can contain using its current
   /// storage.
   ///
-  /// If the array grows larger than its capacity, it discards its current
-  /// storage and allocates a larger one.
+  /// If you add more elements to an array than it can hold with its current
+  /// capacity, it discards its current storage and allocates a larger one.
   ///
   /// The following example creates an array of integers from an array literal,
   /// then appends the elements of another collection. Before appending, the
   /// array allocates new storage that is large enough store the resulting
   /// elements.
   ///
   ///     var numbers = [10, 20, 30, 40, 50]
-  ///     print("Count: \(numbers.count), capacity: \(numbers.capacity)")
-  ///     // Prints "Count: 5, capacity: 5"
+  ///     // numbers.count == 5
+  ///     // numbers.capacity == 5
   ///
   ///     numbers.append(contentsOf: stride(from: 60, through: 100, by: 10))
-  ///     print("Count: \(numbers.count), capacity: \(numbers.capacity)")
-  ///     // Prints "Count: 10, capacity: 12"
+  ///     // numbers.count == 10
+  ///     // numbers.capacity == 12
   public var capacity: Int {
     return _getCapacity()
   }
@@ -1184,13 +1193,19 @@ extension ${Self} : RangeReplaceableCollection, _ArrayProtocol {
   /// unique, mutable, contiguous storage, with space allocated for at least
   /// the requested number of elements.
   ///
-  /// For performance reasons, the newly allocated storage may be larger than
-  /// the requested capacity. Use the array's `capacity` property to determine
-  /// the size of the new storage.
+% if Self != 'ContiguousArray':
+  /// Calling the `reserveCapacity(_:)` method on an array with bridged storage
+  /// triggers a copy to contiguous storage even if the existing storage
+  /// has room to store `minimumCapacity` elements.
+  ///
+% end
+  /// For performance reasons, the size of the newly allocated storage might be
+  /// greater than the requested capacity. Use the array's `capacity` property
+  /// to determine the size of the new storage.
   ///
   /// - Parameter minimumCapacity: The requested number of elements to store.
   ///
-  /// - Complexity: O(*n*), where *n* is the count of the array.
+  /// - Complexity: O(*n*), where *n* is the number of elements in the array.
   @_semantics("array.mutate_unknown")
   public mutating func reserveCapacity(_ minimumCapacity: Int) {
     if _buffer.requestUniqueMutableBackingBuffer(
@@ -1515,7 +1530,6 @@ extension ${Self} {
 
 extension ${Self} {
   /// Calls a closure with a pointer to the array's contiguous storage.
-  /// ${contiguousCaveat}
   ///
   /// Often, the optimizer can eliminate bounds checks within an array
   /// algorithm, but when that fails, invoking the same algorithm on the
@@ -1534,9 +1548,13 @@ extension ${Self} {
   ///     }
   ///     // 'sum' == 9
   ///
+  /// The pointer passed as an argument to `body` is valid only for the
+  /// lifetime of the closure. Do not escape it from the closure for later
+  /// use.
+  ///
   /// - Parameter body: A closure with an `UnsafeBufferPointer` parameter that
-  ///   points to the contiguous storage for the array. If `body` has a return
-  ///   value, it is used as the return value for the
+  ///   points to the contiguous storage for the array. ${contiguousCaveat} If
+  ///   `body` has a return value, it is used as the return value for the
   ///   `withUnsafeBufferPointer(_:)` method. The pointer argument is valid
   ///   only for the duration of the closure's execution.
   /// - Returns: The return value of the `body` closure parameter, if any.
@@ -1549,13 +1567,13 @@ extension ${Self} {
   }
 
   /// Calls the given closure with a pointer to the array's mutable contiguous
-  /// storage.${contiguousCaveat}
+  /// storage.
   ///
   /// Often, the optimizer can eliminate bounds checks within an array
   /// algorithm, but when that fails, invoking the same algorithm on the
   /// buffer pointer passed into your closure lets you trade safety for speed.
   ///
-  /// The following example shows modifying the contents of the
+  /// The following example shows how modifying the contents of the
   /// `UnsafeMutableBufferPointer` argument to `body` alters the contents of
   /// the array:
   ///
@@ -1568,16 +1586,21 @@ extension ${Self} {
   ///     print(numbers)
   ///     // Prints "[2, 1, 4, 3, 5]"
   ///
-  /// - Warning: Do not rely on anything about `self` (the array that is the
-  ///   target of this method) during the execution of the `body` closure: It
-  ///   may not appear to have its correct value.  Instead, use only the
+  /// The pointer passed as an argument to `body` is valid only for the
+  /// lifetime of the closure. Do not escape it from the closure for later
+  /// use.
+  ///
+  /// - Warning: Do not rely on anything about the array that is the target of
+  ///   this method during execution of the `body` closure; it might not
+  ///   appear to have its correct value. Instead, use only the
   ///   `UnsafeMutableBufferPointer` argument to `body`.
   ///
   /// - Parameter body: A closure with an `UnsafeMutableBufferPointer`
-  ///   parameter that points to the contiguous storage for the array. If
-  ///   `body` has a return value, it is used as the return value for the
-  ///   `withUnsafeMutableBufferPointer(_:)` method. The pointer argument is
-  ///   valid only for the duration of the closure's execution.
+  ///   parameter that points to the contiguous storage for the array.
+  ///   ${contiguousCaveat} If `body` has a return value, it is used as the
+  ///   return value for the `withUnsafeMutableBufferPointer(_:)` method. The
+  ///   pointer argument is valid only for the duration of the closure's
+  ///   execution.
   /// - Returns: The return value of the `body` closure parameter, if any.
   ///
   /// - SeeAlso: `withUnsafeBufferPointer`, `UnsafeMutableBufferPointer`
@@ -2099,28 +2122,42 @@ public func != <Element : Equatable>(
 }
 
 extension ${Self} {
-  /// Calls a closure with a view of the array's underlying bytes of memory as a
-  /// Collection of `UInt8`.
+  /// Calls the given closure with a pointer to the underlying bytes of the
+  /// array's mutable contiguous storage.
   ///
-  /// ${contiguousCaveat}
+  /// The array's `Element` type must be a *trivial type*, which can be copied
+  /// with just a bit-for-bit copy without any indirection or
+  /// reference-counting operations. Generally, native Swift types that do not
+  /// contain strong or weak references are trivial, as are imported C structs
+  /// and enums.
   ///
-  /// - Precondition: `Pointee` is a trivial type.
+  /// The following example copies bytes from the `byteValues` array into
+  /// `numbers`, an array of `Int`:
   ///
-  /// The following example shows how you copy bytes into an array:
+  ///     var numbers: [Int32] = [0, 0]
+  ///     var byteValues: [UInt8] = [0x01, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]
   ///
-  ///    var numbers = [Int32](repeating: 0, count: 2)
-  ///    var byteValues: [UInt8] = [0x01, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00]
-  ///    numbers.withUnsafeMutableBytes { destBytes in
-  ///      byteValues.withUnsafeBytes { srcBytes in
-  ///        destBytes.copyBytes(from: srcBytes)
-  ///      }
-  ///    }
-  ///
-  /// - Parameter body: A closure with an `UnsafeRawBufferPointer`
-  ///   parameter that points to the contiguous storage for the array. If `body`
-  ///   has a return value, it is used as the return value for the
-  ///   `withUnsafeMutableBytes(_:)` method. The argument is valid only for the
-  ///   duration of the closure's execution.
+  ///     numbers.withUnsafeMutableBytes { destBytes in
+  ///         byteValues.withUnsafeBytes { srcBytes in
+  ///             destBytes.copyBytes(from: srcBytes)
+  ///         }
+  ///     }
+  ///     // numbers == [1, 2]
+  ///
+  /// The pointer passed as an argument to `body` is valid only for the
+  /// lifetime of the closure. Do not escape it from the closure for later
+  /// use.
+  ///
+  /// - Warning: Do not rely on anything about the array that is the target of
+  ///   this method during execution of the `body` closure; it might not
+  ///   appear to have its correct value. Instead, use only the
+  ///   `UnsafeMutableRawBufferPointer` argument to `body`.
+  ///
+  /// - Parameter body: A closure with an `UnsafeMutableRawBufferPointer`
+  ///   parameter that points to the contiguous storage for the array.
+  ///   ${contiguousCaveat} If `body` has a return value, it is used as the
+  ///   return value for the `withUnsafeMutableBytes(_:)` method. The argument
+  ///   is valid only for the duration of the closure's execution.
   /// - Returns: The return value of the `body` closure parameter, if any.
   ///
   /// - SeeAlso: `withUnsafeBytes`, `UnsafeMutableRawBufferPointer`
@@ -2132,27 +2169,24 @@ extension ${Self} {
     }
   }
 
-  /// Calls a closure with a view of the array's underlying bytes of memory
-  /// as a Collection of `UInt8`.
+  /// Calls the given closure with a pointer to the underlying bytes of the
+  /// array's contiguous storage.
   ///
-  /// ${contiguousCaveat}
-  ///
-  /// - Precondition: `Pointee` is a trivial type.
-  ///
-  /// The following example shows how you copy the contents of an array into a
+  /// The following example copies the bytes of the `numbers` array into a
   /// buffer of `UInt8`:
   ///
-  ///    let numbers = [1, 2, 3]
-  ///    var byteBuffer = [UInt8]()
-  ///    numbers.withUnsafeBytes {
-  ///        byteBuffer += $0
-  ///    }
+  ///     var numbers = [1, 2, 3]
+  ///     var byteBuffer: [UInt8] = []
+  ///     numbers.withUnsafeBytes {
+  ///         byteBuffer.append(contentsOf: $0)
+  ///     }
+  ///     // byteBuffer == [1, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, ...]
   ///
   /// - Parameter body: A closure with an `UnsafeRawBufferPointer` parameter
-  ///   that points to the contiguous storage for the array. If `body` has a
-  ///   return value, it is used as the return value for the
-  ///   `withUnsafeBytes(_:)` method. The argument is valid only for the
-  ///   duration of the closure's execution.
+  ///   that points to the contiguous storage for the array.
+  ///   ${contiguousCaveat} If `body` has a return value, it is used as the
+  ///   return value for the `withUnsafeBytes(_:)` method. The argument is
+  ///   valid only for the duration of the closure's execution.
   /// - Returns: The return value of the `body` closure parameter, if any.
   ///
   /// - SeeAlso: `withUnsafeBytes`, `UnsafeRawBufferPointer`

stdlib/public/core/Bool.swift

@@ -14,10 +14,9 @@
 
 /// A value type whose instances are either `true` or `false`.
 ///
-/// `Bool` represents Boolean values in Swift. Create instances of
-/// `Bool` by using one of the Boolean literals `true` and `false` or by
-/// assigning the result of a Boolean method or operation to a variable or
-/// constant.
+/// `Bool` represents Boolean values in Swift. Create instances of `Bool` by
+/// using one of the Boolean literals `true` or `false`, or by assigning the
+/// result of a Boolean method or operation to a variable or constant.
 ///
 ///     var godotHasArrived = false
 ///
@@ -33,8 +32,8 @@
 ///
 /// Swift uses only simple Boolean values in conditional contexts to help avoid
 /// accidental programming errors and to help maintain the clarity of each
-/// control statement. Unlike other programming languages, in Swift integers
-/// and strings cannot be used where a Boolean value is expected.
+/// control statement. Unlike in other programming languages, in Swift, integers
+/// and strings cannot be used where a Boolean value is required.
 ///
 /// For example, the following code sample does not compile, because it
 /// attempts to use the integer `i` in a logical context:
@@ -52,13 +51,21 @@
 ///         print(i)
 ///         i -= 1
 ///     }
+///
+/// Using Imported Boolean values
+/// =============================
+///
+/// The C `bool` and `Boolean` types and the Objective-C `BOOL` type are all
+/// bridged into Swift as `Bool`. The single `Bool` type in Swift guarantees
+/// that functions, methods, and properties imported from C and Objective-C
+/// have a consistent type interface.
 @_fixed_layout
 public struct Bool {
   internal var _value: Builtin.Int1
 
   /// Creates an instance initialized to `false`.
   ///
-  /// Don't call this initializer directly. Instead, use the Boolean literal
+  /// Do not call this initializer directly. Instead, use the Boolean literal
   /// `false` to create a new `Bool` instance.
   @_transparent
   public init() {
@@ -85,7 +92,7 @@ extension Bool : _ExpressibleByBuiltinBooleanLiteral, ExpressibleByBooleanLitera
   ///
   /// Do not call this initializer directly. It is used by the compiler when
   /// you use a Boolean literal. Instead, create a new `Bool` instance by
-  /// using one of the Boolean literals `true` and `false`.
+  /// using one of the Boolean literals `true` or `false`.
   ///
   ///     var printedMessage = false
   ///

stdlib/public/core/Character.swift

@@ -106,7 +106,7 @@ public struct Character :
 
   /// Creates a character with the specified value.
   ///
-  /// Don't call this initializer directly. It is used by the compiler when you
+  /// Do not call this initializer directly. It is used by the compiler when you
   /// use a string literal to initialize a `Character` instance. For example:
   ///
   ///     let snowflake: Character = "❄︎"
@@ -134,8 +134,9 @@ public struct Character :
 
   /// Creates a character with the specified value.
   ///
-  /// Don't call this initializer directly. It is used by the compiler when you
-  /// use a string literal to initialize a `Character` instance. For example:
+  /// Do not call this initializer directly. It is used by the compiler when
+  /// you use a string literal to initialize a `Character` instance. For
+  /// example:
   ///
   ///     let oBreve: Character = "o\u{306}"
   ///     print(oBreve)