[stdlib] Various documentation improvements (#18013) (#18046)

- Revise Bool.toggle() discussion and fix attribute placement
- Revise to Hasher abstracts and discussions
- Correct the name of the remainder operator
- Clean up deprecations and paste-os w/in UnsafePointer

Author: natecook1000

stdlib/public/core/Bool.swift

@@ -341,16 +341,16 @@ extension Bool {
 }
 
 extension Bool {
-  @inlinable
-  /// Toggles the value of the Boolean. 
+  /// Toggles the Boolean variable's value.
   ///
-  /// Calling this method sets the variable to `true` if it was `false`,
-  /// and sets it to `false` if it was `true`. For example:
+  /// Use this method to toggle a Boolean value from `true` to `false` or from
+  /// `false` to `true`.
   ///
   ///    var bools = [true, false]
   ///
   ///    bools[0].toggle()
-  ///    // bools now contains [false, false]
+  ///    // bools == [false, false]
+  @inlinable
   public mutating func toggle() {
     self = !self
   }

stdlib/public/core/Hasher.swift

@@ -255,8 +255,10 @@ public struct Hasher {
 
   internal var _core: Core
 
-  /// Initialize a new hasher.  The hasher uses a per-execution seed value that
-  /// is set during process startup, usually from a high-quality random source.
+  /// Creates a new hasher.
+  ///
+  /// The hasher uses a per-execution seed value that is set during process
+  /// startup, usually from a high-quality random source.
   @effects(releasenone)
   public init() {
     self._core = Core(seed: Hasher._seed)
@@ -299,8 +301,10 @@ public struct Hasher {
     }
   }
 
-  /// Feed `value` to this hasher, mixing its essential parts into
-  /// the hasher state.
+  /// Adds the given value to this hasher, mixing its essential parts into the
+  /// hasher state.
+  ///
+  /// - Parameter value: A value to add to the hasher.
   @inlinable
   @inline(__always)
   public mutating func combine<H: Hashable>(_ value: H) {
@@ -343,8 +347,10 @@ public struct Hasher {
     _core.combine(bytes: value, count: count)
   }
 
-  /// Feed the contents of `buffer` into this hasher, mixing it into the hasher
-  /// state.
+  /// Adds the contents of the given buffer to this hasher, mixing it into the
+  /// hasher state.
+  ///
+  /// - Parameter bytes: A raw memory buffer.
   @effects(releasenone)
   public mutating func combine(bytes: UnsafeRawBufferPointer) {
     _core.combine(bytes: bytes)
@@ -359,14 +365,16 @@ public struct Hasher {
     return Int(truncatingIfNeeded: _core.finalize())
   }
 
-  /// Finalize the hasher state and return the hash value.
+  /// Finalizes the hasher state and returns the hash value.
   ///
   /// 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.
+  ///
+  /// - Returns: The hash value calculated by the hasher.
   @effects(releasenone)
   public __consuming func finalize() -> Int {
     var core = _core

stdlib/public/core/Integers.swift.gyb

@@ -223,8 +223,8 @@ def operatorComment(operator, fixedWidth):
         '%': """\
   /// Returns the remainder of dividing the first value by the second.
   ///
-  /// The result of the modulo operator (`%`) has the same sign as `lhs` and is
-  /// less than `rhs.magnitude`.
+  /// The result of the remainder operator (`%`) has the same sign as `lhs` and
+  /// is less than `rhs.magnitude`.
   ///
   ///     let x = 22 % 5
   ///     // x == 2

stdlib/public/core/SequenceAlgorithms.swift

@@ -492,6 +492,13 @@ extension Sequence {
   /// Returns a Boolean value indicating whether every element of a sequence
   /// satisfies a given predicate.
   ///
+  /// The following code uses this method to test whether all the names in an
+  /// array have at least five characters:
+  ///
+  ///     let names = ["Sofia", "Camilla", "Martina", "Mateo", "Nicolás"]
+  ///     let allHaveAtLeastFive = names.allSatisfy({ $0.count >= 5 })
+  ///     // allHaveAtLeastFive == true
+  ///
   /// - Parameter predicate: A closure that takes an element of the sequence
   ///   as its argument and returns a Boolean value that indicates whether
   ///   the passed element satisfies a condition.

stdlib/public/core/UnsafePointer.swift.gyb

@@ -51,8 +51,8 @@
 /// initialized before it can be accessed for reading.
 ///
 %if mutable:
-/// You can use methods like `initialize(to:count:)`, `initialize(from:)`, and
-/// `moveInitialize(from:count:)` to initialize the memory referenced by a
+/// You can use methods like `initialize(to:count:)`, `initialize(from:count:)`,
+/// and `moveInitialize(from:count:)` to initialize the memory referenced by a
 /// pointer with a value or series of values.
 ///
 % end
@@ -81,8 +81,9 @@
 /// memory, `uint8Pointer`, will be used for the examples below.
 ///
 % if mutable:
+///     var bytes: [UInt8] = [39, 77, 111, 111, 102, 33, 39, 0]
 ///     let uint8Pointer = UnsafeMutablePointer<UInt8>.allocate(capacity: 8)
-///     uint8Pointer.initialize(from: [39, 77, 111, 111, 102, 33, 39, 0])
+///     uint8Pointer.initialize(from: &bytes, count: 8)
 % else:
 ///     let uint8Pointer: UnsafePointer<UInt8> = fetchEightBytes()
 % end
@@ -416,9 +417,11 @@ public struct ${Self}<Pointee>: _Pointer {
   /// instances and then initializes that memory with the elements of a range.
   ///
   ///     let intPointer = UnsafeMutablePointer<Int>.allocate(capacity: 4)
-  ///     intPointer.initialize(from: 1...4)
+  ///     for i in 0..<4 {
+  ///         (intPointer + i).initialize(to: i)
+  ///     }
   ///     print(intPointer.pointee)
-  ///     // Prints "1"
+  ///     // Prints "0"
   ///
   /// When you allocate memory, always remember to deallocate once you're
   /// finished.
@@ -618,7 +621,7 @@ public struct ${Self}<Pointee>: _Pointer {
   /// The region of memory starting at this pointer and covering `count`
   /// instances of the pointer's `Pointee` type must be uninitialized or
   /// `Pointee` must be a trivial type. After calling
-  /// `initialize(from:count:)`, the region is initialized and the memory
+  /// `moveInitialize(from:count:)`, the region is initialized and the memory
   /// region `source..<(source + count)` is uninitialized.
   ///
   /// - Parameters:
@@ -711,7 +714,7 @@ public struct ${Self}<Pointee>: _Pointer {
   /// The region of memory starting at this pointer and covering `count`
   /// instances of the pointer's `Pointee` type must be initialized or
   /// `Pointee` must be a trivial type. After calling
-  /// `initialize(from:count:)`, the region is initialized and the memory
+  /// `moveAssign(from:count:)`, the region is initialized and the memory
   /// region `source..<(source + count)` is uninitialized.
   ///
   /// - Parameters: