Merge pull request #9574 from natecook1000/nc-fixes-75-1

[stdlib] Various documentation improvements

Author: natecook1000

stdlib/public/SDK/Foundation/NSStringAPI.swift

@@ -95,8 +95,8 @@ if True:
 ///
 ///     let midpoint = absences.count / 2
 ///
-///     let firstHalf = absences.prefix(upTo: midpoint)
-///     let secondHalf = absences.suffix(from: midpoint)
+///     let firstHalf = absences[..<midpoint]
+///     let secondHalf = absences[midpoint...]
 ///
 /// Neither the `firstHalf` nor `secondHalf` slices allocate any new storage
 /// of their own. Instead, each presents a view onto the storage of the
@@ -151,7 +151,7 @@ if True:
 /// Here's an implementation of those steps:
 ///
 ///     if let i = absences.index(where: { $0 > 0 }) {                      // 1
-///         let absencesAfterFirst = absences.suffix(from: i + 1)           // 2
+///         let absencesAfterFirst = absences[(i + 1)...]                   // 2
 ///         if let j = absencesAfterFirst.index(where: { $0 > 0 }) {        // 3
 ///             print("The first day with absences had \(absences[i]).")    // 4
 ///             print("The second day with absences had \(absences[j]).")

stdlib/public/core/Arrays.swift.gyb

@@ -202,9 +202,9 @@ extension Bool {
 }
 
 extension Bool {
-  /// Performs a logical AND operation on two Bool values.
+  /// Performs a logical AND operation on two Boolean values.
   ///
-  /// The logical AND operator (`&&`) combines two Bool values and returns
+  /// The logical AND operator (`&&`) combines two Boolean values and returns
   /// `true` if both of the values are `true`. If either of the values is
   /// `false`, the operator returns `false`.
   ///
@@ -241,9 +241,9 @@ extension Bool {
     return lhs ? try rhs() : false
   }
 
-  /// Performs a logical OR operation on two Bool values.
+  /// Performs a logical OR operation on two Boolean values.
   ///
-  /// The logical OR operator (`||`) combines two Bool values and returns
+  /// The logical OR operator (`||`) combines two Boolean values and returns
   /// `true` if at least one of the values is `true`. If both values are
   /// `false`, the operator returns `false`.
   ///

stdlib/public/core/Bool.swift

@@ -817,12 +817,13 @@ public func type<T, Metatype>(of value: T) -> Metatype {
 ///   behavior for the escapable closure to be stored, referenced, or executed
 ///   after the function returns.
 ///
-/// - Parameter 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
-///   `withoutActuallyEscaping(_:do:)` function.
-/// - Parameter body: A closure that will be immediately executed, receiving an
-///   escapable copy of `closure` as an argument.
+/// - 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
+///     `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.
 @_transparent
 @_semantics("typechecker.withoutActuallyEscaping(_:do:)")

stdlib/public/core/Builtin.swift

@@ -16,12 +16,13 @@
 /// The `Character` type represents a character made up of one or more Unicode
 /// scalar values, grouped by a Unicode boundary algorithm. Generally, a
 /// `Character` instance matches what the reader of a string will perceive as
-/// a single character. The number of visible characters is generally the most
-/// natural way to count the length of a string.
+/// a single character. Strings are collections of `Character` instances, so
+/// the number of visible characters is generally the most natural way to
+/// count the length of a string.
 ///
 ///     let greeting = "Hello! 🐥"
-///     print("Character count: \(greeting.characters.count)")
-///     // Prints "Character count: 8"
+///     print("Length: \(greeting.count)")
+///     // Prints "Length: 8"
 ///
 /// Because each character in a string can be made up of one or more Unicode
 /// code points, the number of characters in a string may not match the length

stdlib/public/core/Character.swift

@@ -448,21 +448,20 @@ public struct IndexingIterator<
 /// at a specific position when using 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
+/// for the index of the first space, and then create a subsequence up to that
 /// position.
 ///
 ///     let text = "Buffalo buffalo buffalo buffalo."
-///     if let firstSpace = text.characters.index(of: " ") {
-///         print(String(text.characters.prefix(upTo: firstSpace)))
+///     if let firstSpace = text.index(of: " ") {
+///         print(text[..<firstSpace])
 ///     }
 ///     // Prints "Buffalo"
 ///
-/// The `firstSpace` constant is an index into the `text.characters`
-/// collection. `firstSpace` is the position of the first space in the
-/// collection. You can store indices in variables, and pass them to
-/// collection algorithms or use them later to access the corresponding
-/// element. In the example above, `firstSpace` is used to extract the prefix
-/// that contains elements up to that index.
+/// The `firstSpace` constant is an index into the `text` string---the position
+/// of the first space in the string. You can store indices in variables, and
+/// pass them to collection algorithms or use them later to access the
+/// 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
@@ -486,7 +485,7 @@ public struct IndexingIterator<
 /// Here's an example of accessing the first character in a string through its
 /// subscript:
 ///
-///     let firstChar = text.characters[text.characters.startIndex]
+///     let firstChar = text[text.startIndex]
 ///     print(firstChar)
 ///     // Prints "B"
 ///
@@ -496,40 +495,33 @@ public struct IndexingIterator<
 /// using the `first` property, which has the value of the first element of
 /// the collection, or `nil` if the collection is empty.
 ///
-///     print(text.characters.first)
+///     print(text.first)
 ///     // Prints "Optional("B")"
 ///
 /// Accessing Slices of a Collection
 /// ================================
 ///
 /// You can access a slice of a collection through its ranged subscript or by
-/// calling methods like `prefix(_:)` or `suffix(from:)`. A slice of a
+/// calling methods like `prefix(while:)` or `suffix(_:)`. A slice of a
 /// collection can contain zero or more of the original collection's elements
 /// and shares the original collection's semantics.
 ///
-/// The following example, creates a `firstWord` constant by using the
-/// `prefix(_:)` method to get a slice of the `text` string's `characters`
-/// view.
+/// The following example creates a `firstWord` constant by using the
+/// `prefix(where:)` method to get a slice of the `text` string.
 ///
-///     let firstWord = text.characters.prefix(7)
-///     print(String(firstWord))
+///     let firstWord = text.prefix(while: { $0 != " " })
+///     print(firstWord)
 ///     // Prints "Buffalo"
 ///
-/// You can retrieve the same slice using other methods, such as finding the
-/// terminating index, and then using the `prefix(upTo:)` method, which takes
-/// an index as its parameter, or by using the view's ranged subscript.
+/// You can retrieve the same slice using the string's ranged subscript, which
+/// takes a range expression.
 ///
-///     if let firstSpace = text.characters.index(of: " ") {
-///         print(text.characters.prefix(upTo: firstSpace))
-///         // Prints "Buffalo"
-///
-///         let start = text.characters.startIndex
-///         print(text.characters[start..<firstSpace])
+///     if let firstSpace = text.index(of: " ") {
+///         print(text[..<firstSpace]
 ///         // Prints "Buffalo"
 ///     }
 ///
-/// The retrieved slice of `text.characters` is equivalent in each of these
-/// cases.
+/// The retrieved slice of `text` is equivalent in each of these cases.
 ///
 /// Slices Share Indices
 /// --------------------
@@ -567,10 +559,9 @@ 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.
+/// 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.
 ///
 /// For example, if you update the last element of the `absences` array from
 /// `0` to `2`, the `secondHalf` slice is unchanged.
@@ -598,7 +589,7 @@ public struct IndexingIterator<
 /// indices or the view itself is being iterated.
 ///
 ///     let word = "Swift"
-///     for character in word.characters {
+///     for character in word {
 ///         print(character)
 ///     }
 ///     // Prints "S"
@@ -607,8 +598,8 @@ public struct IndexingIterator<
 ///     // Prints "f"
 ///     // Prints "t"
 ///
-///     for i in word.characters.indices {
-///         print(word.characters[i])
+///     for i in word.indices {
+///         print(word[i])
 ///     }
 ///     // Prints "S"
 ///     // Prints "w"
@@ -798,6 +789,15 @@ public protocol Collection : _Indexable, Sequence
   ///     print(numbers.prefix(upTo: numbers.startIndex))
   ///     // Prints "[]"
   ///
+  /// Using the `prefix(upTo:)` method is equivalent to using a partial
+  /// half-open range as the collection's subscript. The subscript notation is
+  /// preferred over `prefix(upTo:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[..<i])
+  ///     }
+  ///     // Prints "[10, 20, 30]"
+  ///
   /// - Parameter end: The "past the end" index of the resulting subsequence.
   ///   `end` must be a valid index of the collection.
   /// - Returns: A subsequence up to, but not including, the `end` position.
@@ -825,6 +825,15 @@ public protocol Collection : _Indexable, Sequence
   ///     print(numbers.suffix(from: numbers.endIndex))
   ///     // Prints "[]"
   ///
+  /// Using the `suffix(from:)` method is equivalent to using a partial range
+  /// from the index as the collection's subscript. The subscript notation is
+  /// preferred over `suffix(from:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[i...])
+  ///     }
+  ///     // Prints "[40, 50, 60]"
+  ///
   /// - 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.
@@ -846,6 +855,15 @@ public protocol Collection : _Indexable, Sequence
   ///     }
   ///     // Prints "[10, 20, 30, 40]"
   ///
+  /// Using the `prefix(through:)` method is equivalent to using a partial
+  /// closed range as the collection's subscript. The subscript notation is
+  /// preferred over `prefix(through:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[...i])
+  ///     }
+  ///     // Prints "[10, 20, 30, 40]"
+  ///
   /// - Parameter end: The index of the last element to include in the
   ///   resulting subsequence. `end` must be a valid index of the collection
   ///   that is not equal to the `endIndex` property.
@@ -864,7 +882,7 @@ public protocol Collection : _Indexable, Sequence
   /// through the elements of the collection.
   ///
   ///     let horseName = "Silver"
-  ///     if horseName.characters.isEmpty {
+  ///     if horseName.isEmpty {
   ///         print("I've been through the desert on a horse with no name.")
   ///     } else {
   ///         print("Hi ho, \(horseName)!")
@@ -1319,7 +1337,7 @@ extension Collection {
   /// through the elements of the collection.
   ///
   ///     let horseName = "Silver"
-  ///     if horseName.characters.isEmpty {
+  ///     if horseName.isEmpty {
   ///         print("I've been through the desert on a horse with no name.")
   ///     } else {
   ///         print("Hi ho, \(horseName)!")
@@ -1420,7 +1438,7 @@ extension Collection {
   ///     let cast = ["Vivien", "Marlon", "Kim", "Karl"]
   ///     let lowercaseNames = cast.map { $0.lowercaseString }
   ///     // 'lowercaseNames' == ["vivien", "marlon", "kim", "karl"]
-  ///     let letterCounts = cast.map { $0.characters.count }
+  ///     let letterCounts = cast.map { $0.count }
   ///     // 'letterCounts' == [6, 6, 3, 4]
   ///
   /// - Parameter transform: A mapping closure. `transform` accepts an
@@ -1622,6 +1640,15 @@ extension Collection {
   ///     print(numbers.prefix(upTo: numbers.startIndex))
   ///     // Prints "[]"
   ///
+  /// Using the `prefix(upTo:)` method is equivalent to using a partial
+  /// half-open range as the collection's subscript. The subscript notation is
+  /// preferred over `prefix(upTo:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[..<i])
+  ///     }
+  ///     // Prints "[10, 20, 30]"
+  ///
   /// - Parameter end: The "past the end" index of the resulting subsequence.
   ///   `end` must be a valid index of the collection.
   /// - Returns: A subsequence up to, but not including, the `end` position.
@@ -1652,6 +1679,15 @@ extension Collection {
   ///     print(numbers.suffix(from: numbers.endIndex))
   ///     // Prints "[]"
   ///
+  /// Using the `suffix(from:)` method is equivalent to using a partial range
+  /// from the index as the collection's subscript. The subscript notation is
+  /// preferred over `suffix(from:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[i...])
+  ///     }
+  ///     // Prints "[40, 50, 60]"
+  ///
   /// - 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.
@@ -1676,6 +1712,15 @@ extension Collection {
   ///     }
   ///     // Prints "[10, 20, 30, 40]"
   ///
+  /// Using the `prefix(through:)` method is equivalent to using a partial
+  /// closed range as the collection's subscript. The subscript notation is
+  /// preferred over `prefix(through:)`.
+  ///
+  ///     if let i = numbers.index(of: 40) {
+  ///         print(numbers[...i])
+  ///     }
+  ///     // Prints "[10, 20, 30, 40]"
+  ///
   /// - Parameter end: The index of the last element to include in the
   ///   resulting subsequence. `end` must be a valid index of the collection
   ///   that is not equal to the `endIndex` property.
@@ -1701,25 +1746,20 @@ extension Collection {
   /// that was originally separated by one or more spaces.
   ///
   ///     let line = "BLANCHE:   I don't want realism. I want magic!"
-  ///     print(line.characters.split(whereSeparator: { $0 == " " })
-  ///                          .map(String.init))
+  ///     print(line.split(whereSeparator: { $0 == " " }))
   ///     // Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// The second example passes `1` for the `maxSplits` parameter, so the
   /// original string is split just once, into two new strings.
   ///
-  ///     print(
-  ///         line.characters.split(
-  ///             maxSplits: 1, whereSeparator: { $0 == " " }
-  ///             ).map(String.init))
+  ///     print(line.split(maxSplits: 1, whereSeparator: { $0 == " " }))
   ///     // Prints "["BLANCHE:", "  I don\'t want realism. I want magic!"]"
   ///
   /// The final example passes `false` for the `omittingEmptySubsequences`
   /// parameter, so the returned array contains empty strings where spaces
   /// were repeated.
   ///
-  ///     print(line.characters.split(omittingEmptySubsequences: false, whereSeparator: { $0 == " " })
-  ///                           .map(String.init))
+  ///     print(line.split(omittingEmptySubsequences: false, whereSeparator: { $0 == " " }))
   ///     // Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// - Parameters:
@@ -1801,23 +1841,20 @@ extension Collection where Iterator.Element : Equatable {
   /// was originally separated by one or more spaces.
   ///
   ///     let line = "BLANCHE:   I don't want realism. I want magic!"
-  ///     print(line.characters.split(separator: " ")
-  ///                          .map(String.init))
+  ///     print(line.split(separator: " "))
   ///     // Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// The second example passes `1` for the `maxSplits` parameter, so the
   /// original string is split just once, into two new strings.
   ///
-  ///     print(line.characters.split(separator: " ", maxSplits: 1)
-  ///                           .map(String.init))
+  ///     print(line.split(separator: " ", maxSplits: 1))
   ///     // Prints "["BLANCHE:", "  I don\'t want realism. I want magic!"]"
   ///
   /// The final example passes `false` for the `omittingEmptySubsequences`
   /// parameter, so the returned array contains empty strings where spaces
   /// were repeated.
   ///
-  ///     print(line.characters.split(separator: " ", omittingEmptySubsequences: false)
-  ///                           .map(String.init))
+  ///     print(line.split(separator: " ", omittingEmptySubsequences: false))
   ///     // Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// - Parameters: