Make the user-facing random Generators reproducible

Thanks to the new distributions, this is almost trivial change.

2 files changed, 33 insertions, 3 deletions

diff --git a/docs/faq.md b/docs/faq.md
index 78da167d..608277e2 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -84,9 +84,14 @@ and it is also generally repeatable across versions, but we might break
 it from time to time. E.g. we broke repeatability with previous versions
 in v2.13.4 so that test cases with similar names are shuffled better.
 
-Random generators currently rely on platform's stdlib, specifically
-the distributions from `<random>`. We thus provide no extra guarantee
-above what your platform does. **Important: `<random>`'s distributions
+Since Catch2 vX.Y.Z the random generators use custom distributions,
+that should be repeatable across different platforms, with few caveats.
+For details see the section on random generators in the [Generator
+documentation](generators.md#random-number-generators-details).
+
+Before this version, random generators relied on distributions from
+platform's stdlib. We thus can provide no extra guarantee on top of the
+ones given by your platform. **Important: `<random>`'s distributions
 are not specified to be repeatable across different platforms.**
 
 
diff --git a/docs/generators.md b/docs/generators.md
index 09799752..7929122b 100644
--- a/docs/generators.md
+++ b/docs/generators.md
@@ -189,6 +189,31 @@ TEST_CASE("type conversion", "[generators]") {
 }
 ```
 
+
+### Random number generators: details
+
+> This section applies from Catch2 vX.Y.Z. Before that, random generators
+> were a thin wrapper around distributions from `<random>`.
+
+All of the `random(a, b)` generators in Catch2 currently generate uniformly
+distributed number in closed interval \[a; b\]. This  is different from
+`std::uniform_real_distribution`, which should return numbers in interval
+\[a; b) (but due to rounding can end up returning b anyway), but the
+difference is intentional, so that `random(a, a)` makes sense. If there is
+enough interest from users, we can provide API to pick any of CC, CO, OC,
+or OO ranges.
+
+Unlike `std::uniform_int_distribution`, Catch2's generators also support
+various single-byte integral types, such as `char` or `bool`.
+
+Given the same seed, the output from the integral generators is
+reproducible across different platforms. For floating point generators,
+we only promise reproducibility on platforms that obey the IEEE 754
+standard, and where `float` is 4 bytes and `double` is 8 bytes. We provide
+no guarantees for `long double`, as the internals of `long double` can
+vary wildly across different platforms.
+
+
 ## Generator interface
 
 You can also implement your own generators, by deriving from the