Merge pull request #16177 from lorentey/hashable-docs

[SE-0206] Update Hashable docs for hash(into:)

Author: lorentey

stdlib/public/core/Hashable.swift

@@ -10,26 +10,27 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A type that provides an integer hash value.
-///
-/// You can use any type that conforms to the `Hashable` protocol in a set or
-/// as a dictionary key. Many types in the standard library conform to
-/// `Hashable`: Strings, integers, floating-point and Boolean values, and even
-/// sets provide a hash value by default. Your own custom types can be
-/// hashable as well. When you define an enumeration without associated
-/// values, it gains `Hashable` conformance automatically, and you can add
-/// `Hashable` conformance to your other custom types by adding a single
-/// `hashValue` property.
-///
-/// A hash value, provided by a type's `hashValue` property, is an integer that
-/// is the same for any two instances that compare equally. That is, for two
-/// instances `a` and `b` of the same type, if `a == b`, then
-/// `a.hashValue == b.hashValue`. The reverse is not true: Two instances with
-/// 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.
+/// A type that can be hashed into a `Hasher` to produce an integer hash value.
+///
+/// You can use any type that conforms to the `Hashable` protocol in a set or as
+/// a dictionary key. Many types in the standard library conform to `Hashable`:
+/// Strings, integers, floating-point and Boolean values, and even sets are
+/// hashable by default. Some other types, such as optionals, arrays and ranges
+/// automatically become hashable when their type arguments implement the same.
+///
+/// Your own custom types can be hashable as well. When you define an
+/// enumeration without associated values, it gains `Hashable` conformance
+/// automatically, and you can add `Hashable` conformance to your other custom
+/// types by implementing the `hash(into:)` method. For structs whose stored
+/// properties are all `Hashable`, and for enum types that have all-`Hashable`
+/// associated values, the compiler is able to provide an implementation of
+/// `hash(into:)` automatically.
+///
+/// Hashing a value means feeding its essential components into a hash function,
+/// represented by the `Hasher` type. Essential components are those that
+/// contribute to the type's implementation of `Equatable`. Two instances that
+/// are equal must feed the same values to `Hasher` in `hash(into:)`, in the
+/// same order.
 ///
 /// Conforming to the Hashable Protocol
 /// ===================================
@@ -50,10 +51,10 @@
 ///
 /// 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.
+/// type to conform to `Hashable`, implement the `hash(into:)` function 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 the `hash(into:)` definition.
 ///
 /// 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:
@@ -67,28 +68,25 @@
 /// You'd like to create a set of the grid points where a user has already
 /// tapped. Because the `GridPoint` type is not hashable yet, it can't be used
 /// as the `Element` type for a set. To add `Hashable` conformance, provide an
-/// `==` operator function and a `hashValue` property.
+/// `==` operator function and a `hash(into:)` method.
 ///
 ///     extension GridPoint: Hashable {
-///         var hashValue: Int {
-///             return x.hashValue ^ y.hashValue &* 16777619
-///         }
-///
 ///         static func == (lhs: GridPoint, rhs: GridPoint) -> Bool {
 ///             return lhs.x == rhs.x && lhs.y == rhs.y
 ///         }
+///
+///         func hash(into hasher: inout Hasher) {
+///             hasher.combine(x)
+///             hasher.combine(y)
+///         }
 ///     }
 ///
-/// The `hashValue` property in this example combines the hash value of a grid
-/// point's `x` property with the hash value of its `y` property multiplied by
-/// a prime constant.
+/// The `hash(into:)` method in this example feeds the properties `x` and `y`
+/// to the supplied hasher; these are the same properties compared by the
+/// implementation of the `==` operator function.
 ///
-/// - Note: The example above is a reasonably good hash function for a
-///   simple type. If you're writing a hash function for a custom type, choose
-///   a hashing algorithm that is appropriate for the kinds of data your type
-///   comprises. Set and dictionary performance depends on hash values that
-///   minimize collisions for their associated element and key types,
-///   respectively.
+/// (Because `x` and `y` are both `Hashable` themselves, you could've also let
+/// the compiler synthesize these implementations for you.)
 ///
 /// Now that `GridPoint` conforms to the `Hashable` protocol, you can create a
 /// set of previously tapped grid points.

stdlib/public/core/Hasher.swift

@@ -388,6 +388,9 @@ public struct Hasher {
   /// Finalizing consumes the hasher: it is illegal to finalize a hasher you
   /// don't own, or to perform operations on a finalized hasher. (These may
   /// become compile-time errors in the future.)
+  ///
+  /// Hash values are not guaranteed to be equal across different executions of
+  /// your program. Do not save hash values to use during a future execution.
   @effects(releasenone)
   public __consuming func finalize() -> Int {
     var core = _core