[stdlib] Documentation improvements

- Revise Equatable and Hashable for synthesized requirements
- Complete Strideable and stride(from:...:by:) documentation
- Revise DoubleWidth type docs
- Add complexity notes for Set.index(of:) and .contains(_:)
- Fix typos in Set.formUnion docs
- Add missing axioms for SetAlgebra (SR-6319)
- Improve guidance for description and debugDescription
- Add note about the result of passing duplicate keys to
  Dictionary(uniqueKeysWithValues:)
- Fix typo in BinaryInteger docs
- Update Substring docs with better conversion example
- Improve docs for withMemoryRebound and isKnownUniquelyReferenced
- Add missing docs not propagated from protocols

Author: natecook1000

stdlib/public/core/DoubleWidth.swift.gyb

@@ -11,6 +11,38 @@
 //===----------------------------------------------------------------------===//
 
 /// A fixed-width integer that is twice the size of its base type.
+///
+/// You can use the `DoubleWidth` type to continue calculations with the result
+/// of a full width arithmetic operation. Normally, when you perform a full
+/// width operation, the result is a tuple of the high and low components of
+/// the result.
+///
+///     let a = 2241543570477705381
+///     let b = 186319822866995413
+///     let c = a.multipliedFullWidth(by: b)
+///     // c == (22640526660490081, 7959093232766896457)
+///
+/// The tuple `c` can't be used in any further comparisons or calculations. To
+/// use this value, create a `DoubleWidth` instance from the result. You can
+/// use the `DoubleWidth` instance the way you use any other integer type.
+///
+///     let d = DoubleWidth(a.multipliedFullWidth(by: b))
+///     // d == 417644001000058515200174966092417353
+///
+///     // Check the calculation:
+///     print(d / DoubleWidth(a) == b)
+///     // Prints "true"
+///
+///     if d > Int.max {
+///         print("Too big to be an 'Int'!")
+///     } else {
+///         print("Small enough to fit in an 'Int'")
+///     }
+///     // Prints "Too big to be an 'Int'!"
+///
+/// The `DoubleWidth` type is intended for intermediate calculations, not as a
+/// replacement for a variable-width integer type. Nesting `DoubleWidth`
+/// instances, in particular, can result in undesirable performance.
 @_fixed_layout // FIXME(sil-serialize-all)
 public struct DoubleWidth<Base : FixedWidthInteger>
   : _ExpressibleByBuiltinIntegerLiteral

stdlib/public/core/Equatable.swift

@@ -48,17 +48,28 @@
 /// `Comparable` protocols, which allow more uses of your custom type, such as
 /// constructing sets or sorting the elements of a collection.
 ///
-/// To adopt the `Equatable` protocol, implement the equal-to operator (`==`)
-/// as a static method of your type. The standard library provides an
+/// You can rely on automatic synthesis of the `Equatable` protocol's
+/// requirements for a custom type when you declare `Equatable` conformance in
+/// the type's original declaration and your type meets these criteria:
+///
+/// - For a `struct`, all its stored properties must conform to `Equatable`.
+/// - For an `enum`, all its associated values must conform to `Equatable`. (An
+///   `enum` without associated values has `Equatable` conformance even
+///   without the declaration.)
+///
+/// To customize your type's `Equatable` conformance, to adopt `Equatable` in a
+/// type that doesn't meet the criteria listed above, or to extend an existing
+/// type to conform to `Equatable`, implement the equal-to operator (`==`) as
+/// a static method of your type. The standard library provides an
 /// implementation for the not-equal-to operator (`!=`) for any `Equatable`
 /// type, which calls the custom `==` function and negates its result.
 ///
-/// As an example, consider a `StreetAddress` structure that holds the parts of
-/// a street address: a house or building number, the street name, and an
+/// As an example, consider a `StreetAddress` class that holds the parts of a
+/// street address: a house or building number, the street name, and an
 /// optional unit number. Here's the initial declaration of the
 /// `StreetAddress` type:
 ///
-///     struct StreetAddress {
+///     class StreetAddress {
 ///         let number: String
 ///         let street: String
 ///         let unit: String?
@@ -151,7 +162,7 @@
 /// triple-equals identical-to operator (`===`). For example:
 ///
 ///     let c = a
-///     print(a === c, b === c, separator: ", ")
+///     print(c === a, c === b, separator: ", ")
 ///     // Prints "true, false"
 public protocol Equatable {
   /// Returns a Boolean value indicating whether two values are equal.

stdlib/public/core/FloatingPoint.swift.gyb

@@ -688,7 +688,7 @@ public protocol FloatingPoint: SignedNumeric, Strideable, Hashable {
   ///
   /// If this value and `other` are finite numbers, the remainder is in the
   /// closed range `-abs(other / 2)...abs(other / 2)`. The
-  /// `remainder(dividingBy:)` method is always exact.
+  /// `formRemainder(dividingBy:)` method is always exact.
   ///
   /// - Parameter other: The value to use when dividing this value.
   mutating func formRemainder(dividingBy other: Self)

stdlib/public/core/FloatingPointTypes.swift.gyb

@@ -109,8 +109,14 @@ extension ${Self} : CustomDebugStringConvertible {
 
 extension ${Self}: BinaryFloatingPoint {
 
+  /// A type that can represent the absolute value of any possible value of
+  /// this type.
   public typealias Magnitude = ${Self}
+
+  /// A type that can represent any written exponent.
   public typealias Exponent = Int
+
+  /// A type that represents the encoded significand of a value.
   public typealias RawSignificand = ${RawSignificand}
 
   /// The number of bits used to represent the type's exponent.
@@ -980,6 +986,35 @@ extension ${Self}: BinaryFloatingPoint {
     lhs._value = Builtin.fdiv_FPIEEE${bits}(lhs._value, rhs._value)
   }
 
+  /// Replaces this value with the remainder of itself divided by the given
+  /// value.
+  ///
+  /// For two finite values `x` and `y`, the remainder `r` of dividing `x` by
+  /// `y` satisfies `x == y * q + r`, where `q` is the integer nearest to
+  /// `x / y`. If `x / y` is exactly halfway between two integers, `q` is
+  /// chosen to be even. Note that `q` is *not* `x / y` computed in
+  /// floating-point arithmetic, and that `q` may not be representable in any
+  /// available integer type.
+  ///
+  /// The following example calculates the remainder of dividing 8.625 by 0.75:
+  ///
+  ///     var x = 8.625
+  ///     print(x / 0.75)
+  ///     // Prints "11.5"
+  ///
+  ///     let q = (x / 0.75).rounded(.toNearestOrEven)
+  ///     // q == 12.0
+  ///     x.formRemainder(dividingBy: 0.75)
+  ///     // x == -0.375
+  ///
+  ///     let x1 = 0.75 * q + x
+  ///     // x1 == 8.625
+  ///
+  /// If this value and `other` are finite numbers, the remainder is in the
+  /// closed range `-abs(other / 2)...abs(other / 2)`. The
+  /// `formRemainder(dividingBy:)` method is always exact.
+  ///
+  /// - Parameter other: The value to use when dividing this value.
   @_inlineable // FIXME(sil-serialize-all)
   @_transparent
   public mutating func formRemainder(dividingBy other: ${Self}) {
@@ -1454,10 +1489,13 @@ extension ${Self} {
     return ${Self}(_bits: Builtin.int_fabs_FPIEEE${bits}(_value))
   }
 
-  /// Creates the closest representable value to the given integer.
-  ///
-  /// - Parameter value: The integer to represent as a floating-point value.
   // FIXME(integers): implement properly
+  /// Creates a value that exactly represents the given integer.
+  ///
+  /// If the given integer is outside the representable range of this type or
+  /// can't be represented exactly, the result is `nil`.
+  ///
+  /// - Parameter source: The integer to represent as a floating-point value.
   @_inlineable // FIXME(sil-serialize-all)
   public init?<T : BinaryInteger>(exactly source: T) {
     fatalError()

stdlib/public/core/Hashable.swift

@@ -28,17 +28,32 @@
 /// equal hash values are not necessarily equal to each other.
 ///
 /// - Important: Hash values are not guaranteed to be equal across different
-///   executions of your program. Do not save hash values to use in a
-///   future execution.
+///   executions of your program. Do not save hash values to use in a future
+///   execution.
 ///
 /// Conforming to the Hashable Protocol
 /// ===================================
 ///
 /// To use your own custom type in a set or as the key type of a dictionary,
-/// add `Hashable` conformance to your type by providing a `hashValue`
-/// property. The `Hashable` protocol inherits from the `Equatable` protocol,
-/// so you must also add an equal-to operator (`==`) function for your
-/// custom type.
+/// add `Hashable` conformance to your type. The `Hashable` protocol inherits
+/// from the `Equatable` protocol, so you must also satisfy that protocol's
+/// requirements.
+///
+/// A custom type's `Hashable` and `Equatable` requirements are automatically
+/// synthesized by the compiler when you declare `Hashable` conformance in the
+/// type's original declaration and your type meets these criteria:
+///
+/// - For a `struct`, all its stored properties must conform to `Hashable`.
+/// - For an `enum`, all its associated values must conform to `Hashable`. (An
+///   `enum` without associated values has `Hashable` conformance even without
+///   the declaration.)
+///
+/// To customize your type's `Hashable` conformance, to adopt `Hashable` in a
+/// type that doesn't meet the criteria listed above, or to extend an existing
+/// type to conform to `Hashable`, implement the `hashValue` property in your
+/// custom type. To ensure that your type meets the semantic requirements of
+/// the `Hashable` and `Equatable` protocols, it's a good idea to also
+/// customize your type's `Equatable` conformance to match.
 ///
 /// As an example, consider a `GridPoint` type that describes a location in a
 /// grid of buttons. Here's the initial declaration of the `GridPoint` type:

stdlib/public/core/HashedCollections.swift.gyb

@@ -566,6 +566,8 @@ extension Set : Sequence {
   ///
   /// - Parameter member: An element to look for in the set.
   /// - Returns: `true` if `member` exists in the set; otherwise, `false`.
+  ///
+  /// - Complexity: O(1)
   @_inlineable // FIXME(sil-serialize-all)
   public func contains(_ member: Element) -> Bool {
     return _variantBuffer.maybeGet(member) != nil
@@ -650,6 +652,8 @@ extension Set : Collection {
   /// - Parameter member: An element to search for in the set.
   /// - Returns: The index of `member` if it exists in the set; otherwise,
   ///   `nil`.
+  ///
+  /// - Complexity: O(1)
   @_inlineable // FIXME(sil-serialize-all)
   public func index(of member: Element) -> Index? {
     return _variantBuffer.index(forKey: member)
@@ -1151,7 +1155,7 @@ extension Set : SetAlgebra {
   /// instances of equivalent elements, only the first instance is kept.
   ///
   ///     var attendees: Set = ["Alicia", "Bethany", "Diana"]
-  ///     let visitors = ["Diana", ""Marcia", "Nathaniel"]
+  ///     let visitors = ["Diana", "Marcia", "Nathaniel"]
   ///     attendees.formUnion(visitors)
   ///     print(attendees)
   ///     // Prints "["Diana", "Nathaniel", "Bethany", "Alicia", "Marcia"]"
@@ -1754,9 +1758,10 @@ public struct Dictionary<Key : Hashable, Value> {
   /// Creates a new dictionary from the key-value pairs in the given sequence.
   ///
   /// You use this initializer to create a dictionary when you have a sequence
-  /// of key-value tuples with unique keys. If your sequence might have
-  /// duplicate keys, use the `Dictionary(_:uniquingKeysWith:)` initializer
-  /// instead.
+  /// of key-value tuples with unique keys. Passing a sequence with duplicate
+  /// keys to this initializer results in a runtime error. If your
+  /// sequence might have duplicate keys, use the
+  /// `Dictionary(_:uniquingKeysWith:)` initializer instead.
   ///
   /// The following example creates a new dictionary using an array of strings
   /// as the keys and the integers in a countable range as the values:

stdlib/public/core/Integers.swift.gyb

@@ -1293,7 +1293,7 @@ extension Numeric {
 ///     // r == 82
 ///     //   == 0b01010010
 ///
-///     let s = Int16(truncatingIfNeeded: s)     // extend 'r' to fill 16 bits
+///     let s = Int16(truncatingIfNeeded: r)     // extend 'r' to fill 16 bits
 ///     // s == 82
 ///     //   == 0b00000000_01010010
 ///
@@ -1648,6 +1648,14 @@ ${operatorComment(x.nonMaskingOperator, False)}
 // Strideable conformance
 extension BinaryInteger {
   // FIXME(ABI): using Int as the return type is wrong.
+  /// Returns the distance from this value to the given value, expressed as a
+  /// stride.
+  ///
+  /// For two values `x` and `y`, and a distance `n = x.distance(to: y)`,
+  /// `x.advanced(by: n) == y`.
+  ///
+  /// - Parameter other: The value to calculate the distance to.
+  /// - Returns: The distance from this value to `other`.
   @_inlineable // FIXME(sil-serialize-all)
   @inline(__always)
   public func distance(to other: Self) -> Int {
@@ -1677,6 +1685,17 @@ extension BinaryInteger {
   }
 
   // FIXME(ABI): using Int as the parameter type is wrong.
+  /// Returns a value that is offset the specified distance from this value.
+  ///
+  /// Use the `advanced(by:)` method in generic code to offset a value by a
+  /// specified distance. If you're working directly with numeric values, use
+  /// the addition operator (`+`) instead of this method.
+  ///
+  /// For a value `x`, a distance `n`, and a value `y = x.advanced(by: n)`,
+  /// `x.distance(to: y) == n`.
+  ///
+  /// - Parameter n: The distance to advance this value.
+  /// - Returns: A value that is offset from this value by `n`.
   @_inlineable // FIXME(sil-serialize-all)
   @inline(__always)
   public func advanced(by n: Int) -> Self {
@@ -1696,12 +1715,31 @@ extension BinaryInteger {
 
 extension Int {
   // FIXME(ABI): using Int as the return type is wrong.
+  /// Returns the distance from this value to the given value, expressed as a
+  /// stride.
+  ///
+  /// For two values `x` and `y`, and a distance `n = x.distance(to: y)`,
+  /// `x.advanced(by: n) == y`.
+  ///
+  /// - Parameter other: The value to calculate the distance to.
+  /// - Returns: The distance from this value to `other`.
   @_inlineable // FIXME(sil-serialize-all)
   @_transparent
   public func distance(to other: Int) -> Int {
     return other - self
   }
 
+  /// Returns a value that is offset the specified distance from this value.
+  ///
+  /// Use the `advanced(by:)` method in generic code to offset a value by a
+  /// specified distance. If you're working directly with numeric values, use
+  /// the addition operator (`+`) instead of this method.
+  ///
+  /// For a value `x`, a distance `n`, and a value `y = x.advanced(by: n)`,
+  /// `x.distance(to: y) == n`.
+  ///
+  /// - Parameter n: The distance to advance this value.
+  /// - Returns: A value that is offset from this value by `n`.
   // FIXME(ABI): using Int as the parameter type is wrong.
   @_inlineable // FIXME(sil-serialize-all)
   @_transparent
@@ -3207,6 +3245,7 @@ ${assignmentOperatorComment(x.operator, True)}
   }
 
   // FIXME should be RandomAccessCollection
+  /// A type that represents the words of this integer.
   @_fixed_layout // FIXME(sil-serialize-all)
   public struct Words : BidirectionalCollection {
     public typealias Indices = CountableRange<Int>
@@ -3286,6 +3325,8 @@ ${assignmentOperatorComment(x.operator, True)}
       Builtin.${truncOrExt}OrBitCast_Int${word_bits}_Int${bits}(bits._value))
   }
 
+  /// A type that can represent the absolute value of any possible value of
+  /// this type.
   public typealias Magnitude = ${U}${Self}
 
 % if signed:

stdlib/public/core/LazyCollection.swift

@@ -84,7 +84,8 @@ extension LazyCollection : Sequence {
     return _base.makeIterator()
   }
 
-  /// A value less than or equal to the number of elements in the collection.
+  /// A value less than or equal to the number of elements in the sequence,
+  /// calculated nondestructively.
   ///
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length

stdlib/public/core/ManagedBuffer.swift

@@ -511,6 +511,32 @@ public struct ManagedBufferPointer<Header, Element> : Equatable {
 ///         myStorage.update(withValue: value)
 ///     }
 ///
+/// Use care when calling `isKnownUniquelyReferenced(_:)` from within a Boolean
+/// expression. In debug builds, an instance in the left-hand side of a `&&`
+/// or `||` expression may still be referenced when evaluating the right-hand
+/// side, inflating the instance's reference count. For example, this version
+/// of the `update(withValue)` method will re-copy `myStorage` on every call:
+///
+///     // Copies too frequently:
+///     mutating func badUpdate(withValue value: T) {
+///         if myStorage.shouldCopy || !isKnownUniquelyReferenced(&myStorage) {
+///             myStorage = self.copiedStorage()
+///         }
+///         myStorage.update(withValue: value)
+///     }
+///
+/// To avoid this behavior, swap the call `isKnownUniquelyReferenced(_:)` to
+/// the left-hand side or store the result of the first expression in a local
+/// constant:
+///
+///     mutating func goodUpdate(withValue value: T) {
+///         let shouldCopy = myStorage.shouldCopy
+///         if shouldCopy || !isKnownUniquelyReferenced(&myStorage) {
+///             myStorage = self.copiedStorage()
+///         }
+///         myStorage.update(withValue: value)
+///     }
+///
 /// `isKnownUniquelyReferenced(_:)` checks only for strong references to the
 /// given object---if `object` has additional weak or unowned references, the
 /// result may still be `true`. Because weak and unowned references cannot be

stdlib/public/core/Map.swift

@@ -126,7 +126,8 @@ extension LazyMapCollection: Sequence {
     return Iterator(_base: _base.makeIterator(), _transform: _transform)
   }
 
-  /// A value less than or equal to the number of elements in the collection.
+  /// A value less than or equal to the number of elements in the sequence,
+  /// calculated nondestructively.
   ///
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length

stdlib/public/core/Mirrors.swift.gyb

@@ -46,6 +46,7 @@ extension ${Type[0]} : CustomReflectable {
 }
 
 extension ${Type[0]} : CustomPlaygroundQuickLookable {
+  /// A custom playground Quick Look for the `${Type[0]}` instance.
   @_inlineable // FIXME(sil-serialize-all)
   public var customPlaygroundQuickLook: PlaygroundQuickLook {
     return ${Type[1]}(${Type[2]})