Update random docs to SystemRandomNumberGenerator (#18042)

Author: airspeedswift

stdlib/public/core/Collection.swift

@@ -1044,9 +1044,8 @@ extension Collection {
   ///     let randomName = names.randomElement()!
   ///     // randomName == "Amani"
   ///
-  /// This method uses the default random generator, `Random.default`. The call
-  /// to `names.randomElement()` above is equivalent to calling
-  /// `names.randomElement(using: &Random.default)`.
+  /// This method is equivalent to calling the version that takes a generator, 
+  /// passing in the system's default random generator.
   ///
   /// - Returns: A random element from the collection. If the collection is
   ///   empty, the method returns `nil`.

stdlib/public/core/CollectionAlgorithms.swift

@@ -406,9 +406,8 @@ extension Sequence {
   ///     let shuffledNumbers = numbers.shuffled()
   ///     // shuffledNumbers == [1, 7, 6, 2, 8, 9, 4, 3, 5, 0]
   ///
-  /// This method uses the default random generator, `Random.default`. The call
-  /// to `numbers.shuffled()` above is equivalent to calling
-  /// `numbers.shuffled(using: &Random.default)`.
+  /// This method is equivalent to calling the version that takes a generator, 
+  /// passing in the system's default random generator.
   ///
   /// - Returns: A shuffled array of this sequence's elements.
   ///
@@ -464,9 +463,8 @@ extension MutableCollection where Self : RandomAccessCollection {
   ///     names.shuffle(using: myGenerator)
   ///     // names == ["Luis", "Camila", "Luciana", "Sofía", "Alejandro", "Diego"]
   ///
-  /// This method uses the default random generator, `Random.default`. The call
-  /// to `names.shuffle()` above is equivalent to calling
-  /// `names.shuffle(using: &Random.default)`.
+  /// This method is equivalent to calling the version that takes a generator, 
+  /// passing in the system's default random generator.
   ///
   /// - Complexity: O(*n*)
   @inlinable

stdlib/public/core/FloatingPoint.swift.gyb

@@ -2488,9 +2488,8 @@ where Self.RawSignificand : FixedWidthInteger {
   /// of `range`, some concrete values may be represented more frequently than
   /// others.
   ///
-  /// This method uses the default random generator, `Random.default`. The call
-  /// to `Double.random(in: ${exampleRange})` above is equivalent to calling
-  /// `Double.random(in: ${exampleRange}, using: &Random.default)`.
+  /// 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.
 %   if Range == 'Range':

stdlib/public/core/Integers.swift.gyb

@@ -2591,9 +2591,8 @@ extension FixedWidthInteger {
   ///     // Prints "64"
   ///     // Prints "5"
   ///
-  /// This method uses the default random generator, `Random.default`. The call
-  /// to `Int.random(in: ${exampleRange})` above is equivalent to calling
-  /// `Int.random(in: ${exampleRange}, using: &Random.default)`.
+  /// 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.
 %   if Range == 'Range':

stdlib/public/core/Random.swift

@@ -21,7 +21,7 @@ import SwiftShims
 ///
 /// When providing new APIs that use randomness, provide a version that accepts
 /// a generator conforming to the `RandomNumberGenerator` protocol as well as a
-/// version that uses the default generator. For example, this `Weekday`
+/// version that uses the default system generator. For example, this `Weekday`
 /// enumeration provides static methods that return a random day of the week:
 ///
 ///     enum Weekday: CaseIterable {
@@ -32,7 +32,8 @@ import SwiftShims
 ///         }
 ///
 ///         static func random() -> Weekday {
-///             return Weekday.random(using: &Random.default)
+///             var g = SystemRandomGenerator()
+///             return Weekday.random(using: &g)
 ///         }
 ///     }
 ///
@@ -110,12 +111,11 @@ extension RandomNumberGenerator {
   }
 }
 
-/// The default source of random data.
+/// The system's default source of random data.
 ///
 /// When you generate random values, shuffle a collection, or perform another
-/// operation that depends on random data, this type's `default` property is the
-/// generator used by default. For example, the two method calls in this example
-/// are equivalent:
+/// operation that depends on random data, this type is the generator used by
+/// default. For example, the two method calls in this example are equivalent:
 ///
 ///     let x = Int.random(in: 1...100)
 ///     var g = SystemRandomNumberGenerator()
@@ -125,13 +125,13 @@ extension RandomNumberGenerator {
 /// multiple threads, and uses a cryptographically secure algorithm whenever
 /// possible.
 ///
-/// Platform Implementation of `Random`
-/// ===================================
+/// Platform Implementation of `SystemRandomNumberGenerator`
+/// ========================================================
 ///
-/// While the `SystemRandomNumberGenerator` generator is automatically seeded
-/// and thread-safe on every platform, the cryptographic quality of the stream
-/// of random data produced by the generator may vary. For more detail, see the
-/// documentation for the APIs used by each platform.
+/// While the system generator is automatically seeded and thread-safe on every
+/// platform, the cryptographic quality of the stream of random data produced by
+/// the generator may vary. For more detail, see the documentation for the APIs
+/// used by each platform.
 ///
 /// - Apple platforms use `arc4random_buf(3)`.
 /// - Linux platforms use `getrandom(2)` when available; otherwise, they read