[stdlib] More documentation revisions / consistency fixes.

Author: natecook1000

stdlib/public/core/Arrays.swift.gyb

@@ -1675,10 +1675,10 @@ extension ${Self} {
   ///
   /// - Parameter body: A closure with an `UnsafeBufferPointer` 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
-  ///   `withUnsafeBufferPointer(_:)` method. The pointer argument is valid
-  ///   only for the duration of the method's execution.
-  /// - Returns: The return value of the `body` closure parameter, if any.
+  ///   `body` has a return value, that value is also used as the return value
+  ///   for the `withUnsafeBufferPointer(_:)` method. The pointer argument is
+  ///   valid only for the duration of the method's execution.
+  /// - Returns: The return value, if any, of the `body` closure parameter.
   @_inlineable
   public func withUnsafeBufferPointer<R>(
     _ body: (UnsafeBufferPointer<Element>) throws -> R
@@ -1717,11 +1717,11 @@ extension ${Self} {
   ///
   /// - Parameter body: A closure with an `UnsafeMutableBufferPointer`
   ///   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 method's
-  ///   execution.
-  /// - Returns: The return value of the `body` closure parameter, if any.
+  ///   ${contiguousCaveat} If `body` has a return value, that value is also
+  ///   used as the return value for the `withUnsafeMutableBufferPointer(_:)`
+  ///   method. The pointer argument is valid only for the duration of the
+  ///   method's execution.
+  /// - Returns: The return value, if any, of the `body` closure parameter.
   @_semantics("array.withUnsafeMutableBufferPointer")
   @inline(__always) // Performance: This method should get inlined into the
   // caller such that we can combine the partial apply with the apply in this
@@ -2248,10 +2248,11 @@ extension ${Self} {
   ///
   /// - 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.
+  ///   ${contiguousCaveat} If `body` has a return value, that value is also
+  ///   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, if any, of the `body` closure parameter.
   @_inlineable
   public mutating func withUnsafeMutableBytes<R>(
     _ body: (UnsafeMutableRawBufferPointer) throws -> R
@@ -2282,10 +2283,10 @@ extension ${Self} {
   ///
   /// - Parameter body: A closure with an `UnsafeRawBufferPointer` 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 `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.
+  ///   ${contiguousCaveat} If `body` has a return value, that value is also
+  ///   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, if any, of the `body` closure parameter.
   @_inlineable
   public func withUnsafeBytes<R>(
     _ body: (UnsafeRawBufferPointer) throws -> R

stdlib/public/core/Bool.swift

@@ -159,8 +159,8 @@ extension Bool : Equatable, Hashable {
 extension Bool : LosslessStringConvertible {
   /// Creates a new Boolean value from the given string.
   ///
-  /// If `description` is any string other than `"true"` or `"false"`, the
-  /// result is `nil`. This initializer is case sensitive.
+  /// If the `description` value is any string other than `"true"` or
+  /// `"false"`, the result is `nil`. This initializer is case sensitive.
   ///
   /// - Parameter description: A string representation of the Boolean value.
   public init?(_ description: String) {

stdlib/public/core/Builtin.swift

@@ -82,24 +82,25 @@ func _canBeClass<T>(_: T.Type) -> Int8 {
 /// Returns the bits of the given instance, interpreted as having the specified
 /// type.
 ///
-/// Only use this function to convert the instance passed as `x` to a
-/// layout-compatible type when the conversion is not possible through other
-/// means. Common conversions that are supported by the standard library
+/// Use this function only to convert the instance passed as `x` to a
+/// layout-compatible type when conversion through other means is not
+/// possible. Common conversions supported by the Swift standard library
 /// include the following:
 ///
-/// - To convert an integer value from one type to another, use an initializer
-///   or the `numericCast(_:)` function.
-/// - To perform a bitwise conversion of an integer value to a different type,
-///   use an `init(bitPattern:)` or `init(truncatingBitPattern:)` initializer.
-/// - To convert between a pointer and an integer value with that bit pattern,
-///   or vice versa, use the `init(bitPattern:)` initializer for the
-///   destination type.
-/// - To perform a reference cast, use the casting operators (`as`, `as!`, or
-///   `as?`) or the `unsafeDowncast(_:to:)` function. Do not use
+/// - Value conversion from one integer type to another. Use the destination
+///   type's initializer or the `numericCast(_:)` function.
+/// - Bitwise conversion from one integer type to another. Use the destination
+///   type's `init(extendingOrTruncating:)` or `init(bitPattern:)`
+///   initializer.
+/// - Conversion from a pointer to an integer value with the bit pattern of the
+///   pointer's address in memory, or vice versa. Use the `init(bitPattern:)`
+///   initializer for the destination type.
+/// - Casting an instance of a reference type. Use the casting operators (`as`,
+///   `as!`, or `as?`) or the `unsafeDowncast(_:to:)` function. Do not use
 ///   `unsafeBitCast(_:to:)` with class or pointer types; doing so may
 ///   introduce undefined behavior.
 ///
-/// - Warning: Calling this function breaks the guarantees of Swift's type
+/// - Warning: Calling this function breaks the guarantees of the Swift type
 ///   system; use with extreme care.
 ///
 /// - Parameters:
@@ -656,12 +657,12 @@ func _trueAfterDiagnostics() -> Builtin.Int1 {
 /// particularly when the dynamic type is different from the static type. The
 /// *static type* of a value is the known, compile-time type of the value. The
 /// *dynamic type* of a value is the value's actual type at run-time, which
-/// may be nested inside its concrete type.
+/// can be nested inside its concrete type.
 ///
 /// In the following code, the `count` variable has the same static and dynamic
 /// type: `Int`. When `count` is passed to the `printInfo(_:)` function,
-/// however, the `value` parameter has a static type of `Any`, the type
-/// declared for the parameter, and a dynamic type of `Int`.
+/// however, the `value` parameter has a static type of `Any` (the type
+/// declared for the parameter) and a dynamic type of `Int`.
 ///
 ///     func printInfo(_ value: Any) {
 ///         let type = type(of: value)
@@ -673,7 +674,7 @@ func _trueAfterDiagnostics() -> Builtin.Int1 {
 ///     // '5' of type 'Int'
 ///
 /// The dynamic type returned from `type(of:)` is a *concrete metatype*
-/// (`T.Type`) for a class, structure, enumeration, or other non-protocol type
+/// (`T.Type`) for a class, structure, enumeration, or other nonprotocol type
 /// `T`, or an *existential metatype* (`P.Type`) for a protocol or protocol
 /// composition `P`. When the static type of the value passed to `type(of:)`
 /// is constrained to a class or protocol, you can use that metatype to access
@@ -709,19 +710,22 @@ func _trueAfterDiagnostics() -> Builtin.Int1 {
 /// retrieves the overridden value from the `EmojiSmiley` subclass, instead of
 /// the `Smiley` class's original definition.
 ///
+/// Finding the Dynamic Type in a Generic Context
+/// =============================================
+///
 /// Normally, you don't need to be aware of the difference between concrete and
 /// existential metatypes, but calling `type(of:)` can yield unexpected
 /// results in a generic context with a type parameter bound to a protocol. In
 /// a case like this, where a generic parameter `T` is bound to a protocol
 /// `P`, the type parameter is not statically known to be a protocol type in
-/// the body of the generic function, so `type(of:)` can only produce the
-/// concrete metatype `P.Protocol`.
+/// the body of the generic function. As a result, `type(of:)` can only
+/// produce the concrete metatype `P.Protocol`.
 ///
 /// The following example defines a `printGenericInfo(_:)` function that takes
 /// a generic parameter and declares the `String` type's conformance to a new
 /// protocol `P`. When `printGenericInfo(_:)` is called with a string that has
 /// `P` as its static type, the call to `type(of:)` returns `P.self` instead
-/// of the dynamic type inside the parameter, `String.self`.
+/// of `String.self` (the dynamic type inside the parameter).
 ///
 ///     func printGenericInfo<T>(_ value: T) {
 ///         let type = type(of: value)
@@ -750,8 +754,8 @@ func _trueAfterDiagnostics() -> Builtin.Int1 {
 ///     betterPrintGenericInfo(stringAsP)
 ///     // 'Hello!' of type 'String'
 ///
-/// - Parameter value: The value to find the dynamic type of.
-/// - Returns: The dynamic type, which is a value of metatype type.
+/// - Parameter value: The value for which to find the dynamic type.
+/// - Returns: The dynamic type, which is a metatype instance.
 @_transparent
 @_semantics("typechecker.type(of:)")
 public func type<T, Metatype>(of value: T) -> Metatype {
@@ -776,15 +780,15 @@ public func type<T, Metatype>(of value: T) -> Metatype {
 /// whether all the elements in an array match a predicate. The function won't
 /// compile as written, because a lazy collection's `filter(_:)` method
 /// requires an escaping closure. The lazy collection isn't persisted, so the
-/// `predicate` closure won't actually escape the body of the function, but
-/// even so it can't be used in this way.
+/// `predicate` closure won't actually escape the body of the function;
+/// nevertheless, it can't be used in this way.
 ///
 ///     func allValues(in array: [Int], match predicate: (Int) -> Bool) -> Bool {
 ///         return array.lazy.filter { !predicate($0) }.isEmpty
 ///     }
 ///     // error: closure use of non-escaping parameter 'predicate'...
 ///
-/// `withoutActuallyEscaping(_:do:)` provides a temporarily-escapable copy of
+/// `withoutActuallyEscaping(_:do:)` provides a temporarily escapable copy of
 /// `predicate` that _can_ be used in a call to the lazy view's `filter(_:)`
 /// method. The second version of `allValues(in:match:)` compiles without
 /// error, with the compiler guaranteeing that the `escapablePredicate`
@@ -816,7 +820,7 @@ public func type<T, Metatype>(of value: T) -> Metatype {
 /// returning. Even though the barrier guarantees that neither closure will
 /// escape the function, the `async(execute:)` method still requires that the
 /// closures passed be marked as `@escaping`, so the first version of the
-/// function does not compile. To resolve this, you can use
+/// function does not compile. To resolve these errors, you can use
 /// `withoutActuallyEscaping(_:do:)` to get copies of `f` and `g` that can be
 /// passed to `async(execute:)`.
 ///
@@ -837,13 +841,13 @@ public func type<T, Metatype>(of value: T) -> Metatype {
 ///   after the function returns.
 ///
 /// - Parameters:
-///   - closure: A non-escaping closure value that will be made escapable for
-///     the duration of the execution of the `body` closure. If `body` has a
-///     return value, it is used as the return value for the
+///   - closure: A nonescaping closure value that is made escapable for the
+///     duration of the execution of the `body` closure. If `body` has a
+///     return value, that value is also used as the return value for the
 ///     `withoutActuallyEscaping(_:do:)` function.
-///   - body: A closure that will be immediately executed, receiving an
-///     escapable copy of `closure` as an argument.
-/// - Returns: The return value of the `body` closure, if any.
+///   - body: A closure that is executed immediately with an escapable copy of
+///     `closure` as its argument.
+/// - Returns: The return value, if any, of the `body` closure.
 @_transparent
 @_semantics("typechecker.withoutActuallyEscaping(_:do:)")
 public func withoutActuallyEscaping<ClosureType, ResultType>(

stdlib/public/core/Collection.swift

@@ -420,20 +420,18 @@ public struct IndexingIterator<
 }
 
 /// A sequence whose elements can be traversed multiple times,
-/// nondestructively, and accessed by indexed subscript.
+/// nondestructively, and accessed by an indexed subscript.
 ///
 /// Collections are used extensively throughout the standard library. When you
-/// use arrays, dictionaries, views of a string's contents and other types,
-/// you benefit from the operations that the `Collection` protocol declares
-/// and implements.
-///
-/// In addition to the methods that collections inherit from the `Sequence`
+/// use arrays, dictionaries, and other collections, you benefit from the
+/// operations that the `Collection` protocol declares and implements. In
+/// addition to the operations that collections inherit from the `Sequence`
 /// protocol, you gain access to methods that depend on accessing an element
-/// at a specific position when using a collection.
+/// at a specific position in a collection.
 ///
-/// For example, if you want to print only the first word in a string, search
-/// for the index of the first space, and then create a subsequence up to that
-/// position.
+/// For example, if you want to print only the first word in a string, you can
+/// search for the index of the first space, and then create a substring up to
+/// that position.
 ///
 ///     let text = "Buffalo buffalo buffalo buffalo."
 ///     if let firstSpace = text.index(of: " ") {
@@ -454,17 +452,18 @@ public struct IndexingIterator<
 /// 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
+/// 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
 /// =============================
 ///
-/// You can access an element of a collection through its subscript with any
-/// valid index except the collection's `endIndex` property, a "past the end"
-/// index that does not correspond with any element of the collection.
+/// You can access an element of a collection through its subscript by using
+/// any valid index except the collection's `endIndex` property. This property
+/// is a "past the end" index that does not correspond with any element of the
+/// collection.
 ///
 /// Here's an example of accessing the first character in a string through its
 /// subscript:
@@ -545,7 +544,7 @@ public struct IndexingIterator<
 /// A slice inherits the value or reference semantics of its base collection.
 /// That is, when working with a slice of a mutable collection that has value
 /// semantics, such as an array, mutating the original collection triggers a
-/// copy of that collection, and does not affect the contents of the slice.
+/// copy of that collection and does not affect the contents of the slice.
 ///
 /// For example, if you update the last element of the `absences` array from
 /// `0` to `2`, the `secondHalf` slice is unchanged.
@@ -560,11 +559,12 @@ public struct IndexingIterator<
 /// =======================
 ///
 /// Although a sequence can be consumed as it is traversed, a collection is
-/// guaranteed to be multipass: Any element may be repeatedly accessed by
+/// guaranteed to be *multipass*: Any element can be repeatedly accessed by
 /// saving its index. Moreover, a collection's indices form a finite range of
-/// the positions of the collection's elements. This guarantees the safety of
-/// operations that depend on a sequence being finite, such as checking to see
-/// whether a collection contains an element.
+/// the positions of the collection's elements. The fact that all collections
+/// are finite guarantees the safety of many sequence operations, such as
+/// using the `contains(_:)` method to test whether a collection includes an
+/// element.
 ///
 /// Iterating over the elements of a collection by their positions yields the
 /// same elements in the same order as iterating over that collection using
@@ -598,31 +598,31 @@ public struct IndexingIterator<
 /// elements, make sure that its type conforms to the `Collection` protocol in
 /// order to give a more useful and more efficient interface for sequence and
 /// collection operations. To add `Collection` conformance to your type, you
-/// must declare at least the four following requirements:
+/// must declare at least the following requirements:
 ///
-/// - the `startIndex` and `endIndex` properties,
-/// - a subscript that provides at least read-only access to your type's
-///   elements, and
-/// - the `index(after:)` method for advancing an index into your collection.
+/// - The `startIndex` and `endIndex` properties
+/// - A subscript that provides at least read-only access to your type's
+///   elements
+/// - The `index(after:)` method for advancing an index into your collection
 ///
 /// Expected Performance
 /// ====================
 ///
 /// Types that conform to `Collection` are expected to provide the `startIndex`
 /// and `endIndex` properties and subscript access to elements as O(1)
-/// operations. Types that are not able to guarantee that expected performance
-/// must document the departure, because many collection operations depend on
-/// O(1) subscripting performance for their own performance guarantees.
+/// operations. Types that are not able to guarantee this performance must
+/// document the departure, because many collection operations depend on O(1)
+/// subscripting performance for their own performance guarantees.
 ///
 /// The performance of some collection operations depends on the type of index
 /// that the collection provides. For example, a random-access collection,
-/// which can measure the distance between two indices in O(1) time, will be
-/// able to calculate its `count` property in O(1) time. Conversely, because a
-/// forward or bidirectional collection must traverse the entire collection to
-/// count the number of contained elements, accessing its `count` property is
-/// an O(*n*) operation.
-public protocol Collection : _Indexable, Sequence 
-// FIXME(ABI) (Revert Where Clauses): Restore these 
+/// which can measure the distance between two indices in O(1) time, can
+/// calculate its `count` property in O(1) time. Conversely, because a forward
+/// or bidirectional collection must traverse the entire collection to count
+/// the number of contained elements, accessing its `count` property is an
+/// O(*n*) operation.
+public protocol Collection : _Indexable, Sequence
+// FIXME(ABI) (Revert Where Clauses): Restore these
 // where SubSequence: Collection, Indices: Collection,
 {
   /// A type that represents the number of steps between a pair of