Merge pull request #18596 from natecook1000/nc-4.2-fixes-87-2

[4.2] [stdlib] Documentation revisions

Author: najacque

stdlib/public/core/ClosedRange.swift

@@ -377,7 +377,7 @@ extension ClosedRange: Equatable {
   ///
   /// Two ranges are equal when they have the same lower and upper bounds.
   ///
-  ///     let x: ClosedRange = 5...15
+  ///     let x = 5...15
   ///     print(x == 5...15)
   ///     // Prints "true"
   ///     print(x == 10...20)

stdlib/public/core/Codable.swift.gyb

@@ -1245,7 +1245,7 @@ public enum DecodingError : Error {
   /// for debugging.
   case typeMismatch(Any.Type, Context)
 
-  /// An indication that a non-optional value of the given type was expected,
+  /// An indication that a nonoptional value of the given type was expected,
   /// but a null value was found.
   ///
   /// As associated values, this case contains the attempted type and context

stdlib/public/core/CollectionAlgorithms.swift

@@ -141,7 +141,7 @@ extension BidirectionalCollection {
   ///
   ///     let numbers = [3, 7, 4, -2, 9, -6, 10, 1]
   ///     if let lastNegative = numbers.last(where: { $0 < 0 }) {
-  ///         print("The last negative number is \(firstNegative).")
+  ///         print("The last negative number is \(lastNegative).")
   ///     }
   ///     // Prints "The last negative number is -6."
   ///
@@ -165,7 +165,7 @@ extension BidirectionalCollection {
   /// You can use the predicate to find an element of a type that doesn't
   /// conform to the `Equatable` protocol or to find an element that matches
   /// particular criteria. This example finds the index of the last name that
-  /// begins with the letter "A":
+  /// begins with the letter *A:*
   ///
   ///     let students = ["Kofi", "Abena", "Peter", "Kweku", "Akosua"]
   ///     if let i = students.lastIndex(where: { $0.hasPrefix("A") }) {
@@ -213,7 +213,7 @@ extension BidirectionalCollection where Element : Equatable {
   ///
   /// - Parameter element: An element to search for in the collection.
   /// - Returns: The last index where `element` is found. If `element` is not
-  ///   found in the collection, returns `nil`.
+  ///   found in the collection, this method returns `nil`.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
   @inlinable

stdlib/public/core/Dictionary.swift

@@ -342,7 +342,7 @@ import SwiftShims
 ///
 /// Note that in this example, `imagePaths` is subscripted using a dictionary
 /// index. Unlike the key-based subscript, the index-based subscript returns
-/// the corresponding key-value pair as a non-optional tuple.
+/// the corresponding key-value pair as a nonoptional tuple.
 ///
 ///     print(imagePaths[glyphIndex!])
 ///     // Prints "("star", "/glyphs/star.png")"
@@ -879,6 +879,8 @@ extension Dictionary {
   ///   transformed value of the same or of a different type.
   /// - Returns: A dictionary containing the keys and transformed values of
   ///   this dictionary.
+  ///
+  /// - Complexity: O(*n*), where *n* is the length of the dictionary.
   @inlinable // FIXME(sil-serialize-all)
   public func mapValues<T>(
     _ transform: (Value) throws -> T

stdlib/public/core/Integers.swift.gyb

@@ -124,8 +124,8 @@ def operatorComment(operator, fixedWidth):
   ///
   /// - Note: Overflow checking is not performed in `-Ounchecked` builds.
   ///
-  /// If you want to opt out of overflow checking and ignore any overflow, use
-  /// the overflow addition operator (`&+`).
+  /// If you want to opt out of overflow checking and wrap the result in case
+  /// of any overflow, use the overflow addition operator (`&+`).
   ///
   ///     x &+ 120                // -115
   ///
@@ -161,8 +161,8 @@ def operatorComment(operator, fixedWidth):
   ///
   /// - Note: Overflow checking is not performed in `-Ounchecked` builds.
   ///
-  /// If you want to opt out of overflow checking and ignore any overflow, use
-  /// the overflow subtraction operator (`&-`).
+  /// If you want to opt out of overflow checking and wrap the result in case
+  /// of any overflow, use the overflow subtraction operator (`&-`).
   ///
   ///     x &- 50                // 227
   ///
@@ -198,8 +198,8 @@ def operatorComment(operator, fixedWidth):
   ///
   /// - Note: Overflow checking is not performed in `-Ounchecked` builds.
   ///
-  /// If you want to opt out of overflow checking and ignore any overflow, use
-  /// the overflow multiplication operator (`&*`).
+  /// If you want to opt out of overflow checking and wrap the result in case
+  /// of any overflow, use the overflow multiplication operator (`&*`).
   ///
   ///     x &* 21                // -115
   ///
@@ -224,7 +224,7 @@ def operatorComment(operator, fixedWidth):
   /// Returns the remainder of dividing the first value by the second.
   ///
   /// The result of the remainder operator (`%`) has the same sign as `lhs` and
-  /// is less than `rhs.magnitude`.
+  /// has a magnitude less than `rhs.magnitude`.
   ///
   ///     let x = 22 % 5
   ///     // x == 2
@@ -241,52 +241,76 @@ def operatorComment(operator, fixedWidth):
   ///   - rhs: The value to divide `lhs` by. `rhs` must not be zero.
 """,
         '&+': """\
-  /// Returns the sum of the two given values, discarding any overflow.
+  /// Returns the sum of the two given values, wrapping the result in case of
+  /// any overflow.
   ///
-  /// The masking addition operator (`&+`) silently discards any overflow that
-  /// occurs during the operation. In the following example, the sum of `100`
-  /// and `121` is greater than the maximum representable `Int8` value, so the
-  /// result is the overflowed value:
+  /// The overflow addition operator (`&+`) discards any bits that overflow the
+  /// fixed width of the integer type. In the following example, the sum of
+  /// `100` and `121` is greater than the maximum representable `Int8` value,
+  /// so the result is the partial value after discarding the overflowing
+  /// bits.
   ///
   ///     let x: Int8 = 10 &+ 21
   ///     // x == 31
   ///     let y: Int8 = 100 &+ 121
   ///     // y == -35 (after overflow)
   ///
+  /// For more about arithmetic with overflow operators, see [Overflow
+  /// Operators][overflow] in *[The Swift Programming Language][tspl]*.
+  ///
+  /// [overflow]: https://docs.swift.org/swift-book/LanguageGuide/AdvancedOperators.html#ID37
+  /// [tspl]: https://docs.swift.org/swift-book/
+  ///
   /// - Parameters:
   ///   - lhs: The first value to add.
   ///   - rhs: The second value to add.
 """,
         '&-': """\
-  /// Returns the difference of the two given values, discarding any overflow.
+  /// Returns the difference of the two given values, wrapping the result in
+  /// case of any overflow.
   ///
-  /// The masking subtraction operator (`&-`) silently discards any overflow
-  /// that occurs during the operation. In the following example, the
+  /// The overflow subtraction operator (`&-`) discards any bits that overflow
+  /// the fixed width of the integer type. In the following example, the
   /// difference of `10` and `21` is less than zero, the minimum representable
-  /// `UInt` value, so the result is the overflowed value:
+  /// `UInt` value, so the result is the partial value after discarding the
+  /// overflowing bits.
   ///
   ///     let x: UInt8 = 21 &- 10
   ///     // x == 11
   ///     let y: UInt8 = 10 &- 21
   ///     // y == 245 (after overflow)
   ///
+  /// For more about arithmetic with overflow operators, see [Overflow
+  /// Operators][overflow] in *[The Swift Programming Language][tspl]*.
+  ///
+  /// [overflow]: https://docs.swift.org/swift-book/LanguageGuide/AdvancedOperators.html#ID37
+  /// [tspl]: https://docs.swift.org/swift-book/
+  ///
   /// - Parameters:
   ///   - lhs: A numeric value.
   ///   - rhs: The value to subtract from `lhs`.
 """,
         '&*': """\
-  /// Returns the product of the two given values, discarding any overflow.
+  /// Returns the product of the two given values, wrapping the result in case
+  /// of any overflow.
   ///
-  /// The masking multiplication operator (`&*`) silently discards any overflow
-  /// that occurs during the operation. In the following example, the product
-  /// of `10` and `50` is greater than the maximum representable `Int8` value,
-  /// so the result is the overflowed value:
+  /// The overflow multiplication operator (`&*`) discards any bits that
+  /// overflow the fixed width of the integer type. In the following example,
+  /// the product of `10` and `50` is greater than the maximum representable
+  /// `Int8` value, so the result is the partial value after discarding the
+  /// overflowing bits.
   ///
   ///     let x: Int8 = 10 &* 5
   ///     // x == 50
   ///     let y: Int8 = 10 &* 50
   ///     // y == -12 (after overflow)
   ///
+  /// For more about arithmetic with overflow operators, see [Overflow
+  /// Operators][overflow] in *[The Swift Programming Language][tspl]*.
+  ///
+  /// [overflow]: https://docs.swift.org/swift-book/LanguageGuide/AdvancedOperators.html#ID37
+  /// [tspl]: https://docs.swift.org/swift-book/
+  ///
   /// - Parameters:
   ///   - lhs: The first value to multiply.
   ///   - rhs: The second value to multiply.
@@ -587,7 +611,8 @@ def assignmentOperatorComment(operator, fixedWidth):
   /// Divides the first value by the second and stores the remainder in the
   /// left-hand-side variable.
   ///
-  /// The result has the same sign as `lhs` and is less than `rhs.magnitude`.
+  /// The result has the same sign as `lhs` and has a magnitude less than
+  /// `rhs.magnitude`.
   ///
   ///     var x = 22
   ///     x %= 5
@@ -606,13 +631,14 @@ def assignmentOperatorComment(operator, fixedWidth):
   ///   - rhs: The value to divide `lhs` by. `rhs` must not be zero.
 """,
         '&+': """\
-  /// Adds two values and stores the result in the left-hand-side variable, 
-  /// discarding any overflow.
+  /// Adds two values and stores the result in the left-hand-side variable,
+  /// wrapping any overflow.
   ///
-  /// The masking addition assignment operator (`&+=`) silently discards any 
-  /// overflow that occurs during the operation. In the following example, the 
-  /// sum of `100` and `121` is greater than the maximum representable `Int8` 
-  /// value, so the result is the overflowed value:
+  /// The masking addition assignment operator (`&+=`) silently wraps any
+  /// overflow that occurs during the operation. In the following example, the
+  /// sum of `100` and `121` is greater than the maximum representable `Int8`
+  /// value, so the result is the partial value after discarding the
+  /// overflowing bits.
   ///
   ///     var x: Int8 = 10
   ///     x &+= 21
@@ -621,18 +647,25 @@ def assignmentOperatorComment(operator, fixedWidth):
   ///     y &+= 121
   ///     // y == -35 (after overflow)
   ///
+  /// For more about arithmetic with overflow operators, see [Overflow
+  /// Operators][overflow] in *[The Swift Programming Language][tspl]*.
+  ///
+  /// [overflow]: https://docs.swift.org/swift-book/LanguageGuide/AdvancedOperators.html#ID37
+  /// [tspl]: https://docs.swift.org/swift-book/
+  ///
   /// - Parameters:
   ///   - lhs: The first value to add.
   ///   - rhs: The second value to add.
 """,
         '&-': """\
   /// Subtracts the second value from the first and stores the difference in the
-  /// left-hand-side variable, discarding any overflow.
+  /// left-hand-side variable, wrapping any overflow.
   ///
-  /// The masking subtraction assignment operator (`&-=`) silently discards any
+  /// The masking subtraction assignment operator (`&-=`) silently wraps any
   /// overflow that occurs during the operation. In the following example, the
   /// difference of `10` and `21` is less than zero, the minimum representable
-  /// `UInt` value, so the result is the overflowed value:
+  /// `UInt` value, so the result is the result is the partial value after
+  /// discarding the overflowing bits.
   ///
   ///     var x: Int8 = 21
   ///     x &-= 10
@@ -641,18 +674,25 @@ def assignmentOperatorComment(operator, fixedWidth):
   ///     y &-= 21
   ///     // y == 245 (after overflow)
   ///
+  /// For more about arithmetic with overflow operators, see [Overflow
+  /// Operators][overflow] in *[The Swift Programming Language][tspl]*.
+  ///
+  /// [overflow]: https://docs.swift.org/swift-book/LanguageGuide/AdvancedOperators.html#ID37
+  /// [tspl]: https://docs.swift.org/swift-book/
+  ///
   /// - Parameters:
   ///   - lhs: A numeric value.
   ///   - rhs: The value to subtract from `lhs`.
 """,
         '&*': """\
   /// Multiplies two values and stores the result in the left-hand-side
-  /// variable, discarding any overflow.
+  /// variable, wrapping any overflow.
   ///
-  /// The masking multiplication assignment operator (`&*=`) silently discards 
-  /// any overflow that occurs during the operation. In the following example, 
-  /// the product of `10` and `50` is greater than the maximum representable 
-  /// `Int8` value, so the result is the overflowed value:
+  /// The masking multiplication assignment operator (`&*=`) silently wraps
+  /// any overflow that occurs during the operation. In the following example,
+  /// the product of `10` and `50` is greater than the maximum representable
+  /// `Int8` value, so the result is the partial value after discarding the
+  /// overflowing bits.
   ///
   ///     var x: Int8 = 10
   ///     x &*= 5
@@ -661,6 +701,12 @@ def assignmentOperatorComment(operator, fixedWidth):
   ///     y &*= 50
   ///     // y == -12 (after overflow)
   ///
+  /// For more about arithmetic with overflow operators, see [Overflow
+  /// Operators][overflow] in *[The Swift Programming Language][tspl]*.
+  ///
+  /// [overflow]: https://docs.swift.org/swift-book/LanguageGuide/AdvancedOperators.html#ID37
+  /// [tspl]: https://docs.swift.org/swift-book/
+  ///
   /// - Parameters:
   ///   - lhs: The first value to multiply.
   ///   - rhs: The second value to multiply.
@@ -1173,6 +1219,15 @@ ${operatorComment(x.operator, False)}
 /// declaring conformance to the protocol and ensuring that the values of your
 /// type support negation. To customize your type's implementation, provide
 /// your own mutating `negate()` method.
+///
+/// When the additive inverse of a value is unrepresentable in a conforming
+/// type, the operation should either trap or return an exceptional value. For
+/// example, using the negation operator (prefix `-`) with `Int.min` results in
+/// a runtime error.
+///
+///     let x = Int.min
+///     let y = -x
+///     // Overflow error
 public protocol SignedNumeric : Numeric {
   /// Returns the additive inverse of the specified value.
   ///
@@ -1201,6 +1256,14 @@ public protocol SignedNumeric : Numeric {
   ///     var x = 21
   ///     x.negate()
   ///     // x == -21
+  ///
+  /// The resulting value must be representable within the value's type. In
+  /// particular, negating a signed, fixed-width integer type's minimum
+  /// results in a value that cannot be represented.
+  ///
+  ///     var y = Int8.min
+  ///     y.negate()
+  ///     // Overflow error
   mutating func negate()
 }
 
@@ -1238,6 +1301,14 @@ extension SignedNumeric {
   ///     var x = 21
   ///     x.negate()
   ///     // x == -21
+  ///
+  /// The resulting value must be representable within the value's type. In
+  /// particular, negating a signed, fixed-width integer type's minimum
+  /// results in a value that cannot be represented.
+  ///
+  ///     var y = Int8.min
+  ///     y.negate()
+  ///     // Overflow error
   @inlinable // FIXME(sil-serialize-all)
   @_transparent
   public mutating func negate() {
@@ -1680,7 +1751,7 @@ ${assignmentOperatorComment(x.nonMaskingOperator, False)}
   ///
   /// - Parameter rhs: The value to divide this value by.
   /// - Returns: A tuple containing the quotient and remainder of this value
-  ///   divided by `rhs`.
+  ///   divided by `rhs`. The remainder has the same sign as `rhs`.
   func quotientAndRemainder(dividingBy rhs: Self)
     -> (quotient: Self, remainder: Self)
 
@@ -2618,7 +2689,7 @@ extension FixedWidthInteger {
   ///     // Prints "64"
   ///     // Prints "5"
   ///
-  /// This method is equivalent to calling the version that takes a generator, 
+  /// This method is equivalent to calling the version that takes a generator,
   /// passing in the system's default random generator.
   ///
   /// - Parameter range: The range in which to create a random value.