Documentation update for Random class

Examples added

Closes #47986
#47986

GitOrigin-RevId: ecb3a42
Change-Id: I3c3a406482be6cb55bb01aba4f78c74ae2d7648f
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/225120
Reviewed-by: Lasse Nielsen <[email protected]>
Commit-Queue: Lasse Nielsen <[email protected]>

Author: jpsiitonen

sdk/lib/math/random.dart

@@ -10,6 +10,24 @@ part of dart.math;
 /// not suitable for cryptographic purposes.
 ///
 /// Use the [Random.secure]() constructor for cryptographic purposes.
+///
+/// To create a non-negative random integer uniformly distributed in the range
+/// from 0, inclusive, to max, exclusive, use [nextInt(int max)].
+/// ```dart
+/// var intValue = Random().nextInt(10); // Value is >= 0 and < 10.
+/// intValue = Random().nextInt(100) + 50; // Value is >= 50 and < 150.
+/// ```
+/// To create a non-negative random floating point value uniformly distributed
+/// in the range from 0.0, inclusive, to 1.0, exclusive, use [nextDouble].
+/// ```dart
+/// var doubleValue = Random().nextDouble(); // Value is >= 0.0 and < 1.0.
+/// doubleValue = Random().nextDouble() * 256; // Value is >= 0.0 and < 256.0.
+/// ```
+/// To create a random Boolean value, use [nextBool].
+/// ```dart
+/// var boolValue = Random().nextBool(); // true or false, with equal chance.
+/// ```
+///
 abstract class Random {
   /// Creates a random number generator.
   ///
@@ -29,12 +47,29 @@ abstract class Random {
   ///
   /// Implementation note: The default implementation supports [max] values
   /// between 1 and (1<<32) inclusive.
+  ///
+  /// Example:
+  /// ```dart
+  /// var intValue = Random().nextInt(10); // Value is >= 0 and < 10.
+  /// intValue = Random().nextInt(100) + 50; // Value is >= 50 and < 150.
+  /// ```
   int nextInt(int max);
 
   /// Generates a non-negative random floating point value uniformly distributed
   /// in the range from 0.0, inclusive, to 1.0, exclusive.
+  ///
+  /// Example:
+  /// ```dart
+  /// var doubleValue = Random().nextDouble(); // Value is >= 0.0 and < 1.0.
+  /// doubleValue = Random().nextDouble() * 256; // Value is >= 0.0 and < 256.0.
+  /// ```
   double nextDouble();
 
   /// Generates a random boolean value.
+  ///
+  /// Example:
+  /// ```dart
+  /// var boolValue = Random().nextBool(); // true or false, with equal chance.
+  /// ```
   bool nextBool();
 }