Improve BitGen stability documentation
Several problems with the previous documentation:
* It said it's stable "within the same binary" but not stable "across multiple binary invocations". Those statements contradict each other.
* It said "in the same binary will not produce the same sequence of variates within the same binary", which is repetitive since it says "in the same binary" twice.
* The comments about the seed sequence were not all next to each other, they were split apart by a rand.req.urng comment.
* It implied that process stability is all you get, whereas generally you also get changelist stability.
* It said you can use a seed sequence with SharedBitGen, but you can't.
* It said there is more info in std_seed_seq.h , but there isn't.
PiperOrigin-RevId: 501389708
Change-Id: I5e3dbc3548cc051265b8d004191c23147eccecc3
diff --git a/absl/random/random.h b/absl/random/random.h
index 71b6309..7672086 100644
--- a/absl/random/random.h
+++ b/absl/random/random.h
@@ -68,7 +68,7 @@
//
// `absl::BitGen` may be constructed with an optional seed sequence type,
// conforming to [rand.req.seed_seq], which will be mixed with additional
-// non-deterministic data.
+// non-deterministic data as detailed below.
//
// Example:
//
@@ -79,16 +79,16 @@
// // Generate an integer value in the closed interval [1,6]
// int die_roll2 = absl::uniform_int_distribution<int>(1, 6)(gen_with_seed);
//
+// Constructing two `absl::BitGen`s with the same seed sequence in the same
+// process will produce the same sequence of variates, but need not do so across
+// multiple processes even if they're executing the same binary.
+//
// `absl::BitGen` meets the requirements of the Uniform Random Bit Generator
// (URBG) concept as per the C++17 standard [rand.req.urng] though differs
// slightly with [rand.req.eng]. Like its standard library equivalents (e.g.
// `std::mersenne_twister_engine`) `absl::BitGen` is not cryptographically
// secure.
//
-// Constructing two `absl::BitGen`s with the same seed sequence in the same
-// binary will produce the same sequence of variates within the same binary, but
-// need not do so across multiple binary invocations.
-//
// This type has been optimized to perform better than Mersenne Twister
// (https://en.wikipedia.org/wiki/Mersenne_Twister) and many other complex URBG
// types on modern x86, ARM, and PPC architectures.
@@ -147,7 +147,7 @@
//
// `absl::InsecureBitGen` may be constructed with an optional seed sequence
// type, conforming to [rand.req.seed_seq], which will be mixed with additional
-// non-deterministic data. (See std_seed_seq.h for more information.)
+// non-deterministic data, as detailed in the `absl::BitGen` comment.
//
// `absl::InsecureBitGen` meets the requirements of the Uniform Random Bit
// Generator (URBG) concept as per the C++17 standard [rand.req.urng] though
