Update after feedback

Author: RaimoNiskanen

lib/stdlib/src/rand.erl

@@ -40,14 +40,17 @@ PRNGs in general, and so the algorithms in this module, are mostly used
 for test and simulation.  They are designed for good statistical
 quality and high generation speed.
 
-An generator algorithm, for each iteration, takes a state as input
+A generator algorithm, for each iteration, takes a state as input
 and produces a raw pseudo random number and a new state to be used
 for the next iteration.
 
 A particular state always produces the same number and new state.
 The initial state is produced from a [seed](`seed/1`).
 This makes it possible to repeat for example a simulation with the same
 random number sequence, by re-using the same seed.
+There are also the functions `export_seed/0` and `export_seed_s/1`
+that captures the PRNG state in an `t:export_state/0` that
+can be used to start from a known state.
 
 This property, and others, make the algorithms in this module
 unsuitable for cryptographical applications, but in the `m:crypto` module
@@ -56,19 +59,19 @@ there are suitable generators, for this module's
 See `crypto:rand_seed_s/0` and `crypto:rand_seed_alg_s/1`.
 
 At the end of this module documentation there are some
-[niche algorithms](#niche-algorithms) that does not use
+[niche algorithms](#niche-algorithms) that do not use
 this module's normal [plug-in framework](#plug-in-framework).
-They may be useful for special purposes like fast generation
+They are useful for special purposes like fast generation
 when quality is not essential, for seeding other generators, and such.
 
 [](){: #plug-in-framework } Plug-in framework
 ---------------------------------------------
 
 The raw pseudo random numbers produced by the base generators
-are only suitable in some cases such as power of two ranges
+are only appropriate in some cases such as power of two ranges
 less than the generator size, and some have quirks,
 for example weak low bits.  Therefore, the Plug-in Framework
-implements a common [API](#plug-in-framework-api) to all base generator,
+implements a common [API](#plug-in-framework-api) for all base generators,
 that add essential or useful funcionality:
 
 * Keeping the generator [state](`seed/1`) in the process dictionary.
@@ -93,7 +96,7 @@ A generator has to be initialized.  This is done by one of the
 `seed/1` or `seed_s/1` functions, which also select which
 [algorithm](#algorithms) to use.  The `seed/1` functions
 store the generator and state in the process dictionary,
-while the `seed_s/1` functions do not, which requires
+while the `seed_s/1` functions only return the state, which requires
 the calling code to handle the state and updates to it.
 
 The seed functions that do not have a `Seed` value as an argument
@@ -113,7 +116,8 @@ Sibling functions without that suffix take an implicit state from
 and store the new state in the process dictionary, and only return
 their "interesting " output value.  If the process dictionary
 does not contain a state, [`seed(default)`](`seed/1`)
-is implicitly called to create an automatic seed as initial state.
+is implicitly called to create an automatic seed for the
+[_default algorithm_](#default-algorithm) as initial state.
 
 #### _Usage_
 
@@ -123,7 +127,7 @@ functions, which also selects a PRNG algorithm.
 Then call a [Plug-in framework API](#plug-in-framework-api) function
 either with an explicit state from the seed function
 and use the returned new state in the next call,
-or call an API function without an explicit state
+or call an API function without an explicit state argument
 to operate on the state in the process dictionary.
 
 #### _Examples_
@@ -159,7 +163,7 @@ true
 %% with an automatic default seed, then generate
 %% a floating point number:
 %%
-5> _ = rand:seed(exro928ss).
+5> rand:seed(exro928ss).
 6> R2 = rand:uniform(),
    is_float(R2) andalso 0.0 =< R2 andalso R2 < 1.0.
 true
@@ -168,10 +172,9 @@ true
 %% with a specified seed, then generate
 %% a floating point number:
 %%
-7> _ = rand:seed(exro928ss, 123456789).
-8> R3 = rand:uniform(),
-   is_float(R3) andalso 0.0 =< R3 andalso R3 < 1.0.
-true
+7> rand:seed(exro928ss, 123456789).
+8> R3 = rand:uniform().
+0.48303622772415256
 
 %% Select and initialize a specific algorithm,
 %% with an automatic default seed, using the functional API
@@ -236,9 +239,10 @@ per generator bit.
 
 By using a jump function instead of starting several generators
 from different seeds it is assured that the generated sequences
-do not overlap.  Two different seeds may accidentally start
-the generators in sequence positions that are close to each other,
-but a jump function jumps to a sequence position very far ahead.
+do not overlap.  The alternative of using different seeds
+may accidentally start the generators in sequence positions
+that are close to each other, but a jump function jumps
+to a sequence position very far ahead.
 
 To create numbers with normal distribution the
 [Ziggurat Method by Marsaglia and Tsang](http://www.jstatsoft.org/v05/i08)
@@ -248,9 +252,9 @@ The following algorithms are provided:
 
 - **`exsss`**, the [_default algorithm_](#default-algorithm)
   *(Since OTP 22.0)*  
-  Xorshift116\*\*, 58 bits precision and period of 2^116-1
+  Xorshift116\*\*, 58 bits precision and period of 2^116-1.
 
-  Jump function: equivalent to 2^64 calls
+  Jump function: equivalent to 2^64 calls.
 
   This is the Xorshift116 generator combined with the StarStar scrambler from
   the 2018 paper by David Blackman and Sebastiano Vigna:
@@ -265,9 +269,9 @@ The following algorithms are provided:
   its statistical qualities.
 
 - **`exro928ss`** *(Since OTP 22.0)*  
-  Xoroshiro928\*\*, 58 bits precision and a period of 2^928-1
+  Xoroshiro928\*\*, 58 bits precision and a period of 2^928-1.
 
-  Jump function: equivalent to 2^512 calls
+  Jump function: equivalent to 2^512 calls.
 
   This is a 58 bit version of Xoroshiro1024\*\*, from the 2018 paper by
   David Blackman and Sebastiano Vigna:
@@ -280,25 +284,29 @@ The following algorithms are provided:
   Many thanks to Sebastiano Vigna for his help with the 58 bit adaption.
 
 - **`exrop`** *(Since OTP 20.0)*  
-  Xoroshiro116+, 58 bits precision and period of 2^116-1
+  Xoroshiro116+, 58 bits precision and period of 2^116-1.
 
-  Jump function: equivalent to 2^64 calls
+  Jump function: equivalent to 2^64 calls.
 
 - **`exs1024s`** *(Since OTP 20.0)*  
   Xorshift1024\*, 64 bits precision and a period of 2^1024-1
 
-  Jump function: equivalent to 2^512 calls
+  Jump function: equivalent to 2^512 calls.
+
+  Since this generator operates on 64-bit integers that are bignums
+  on a 64 bit platforms, it is much slower than `exro928ss` above.
 
 - **`exsp`** *(Since OTP 20.0)*  
   Xorshift116+, 58 bits precision and period of 2^116-1
 
-  Jump function: equivalent to 2^64 calls
+  Jump function: equivalent to 2^64 calls.
 
   This is a corrected version of a previous
   [_default algorithm_](#default-algorithm) (`exsplus`, _deprecated_),
   that was superseded by Xoroshiro116+ (`exrop`).  Since this algorithm
-  does not use rotate it executes a little (say < 15%) faster than `exrop`
-  (that has to do a 58 bit rotate, for which there is no native instruction).
+  does not use rotate operations it executes a little (say < 15%) faster
+  than `exrop` (that has to do a 58 bit rotate,
+  for which there is no native instruction).
   See the [algorithms' homepage](http://xorshift.di.unimi.it).
 
 [](){: #default-algorithm }
@@ -310,7 +318,9 @@ required, ensure to always use `seed/1` to initialize the state.
 
 Which algorithm that is the default may change between Erlang/OTP releases,
 and is selected to be one with high speed, small state and "good enough"
-statistical properties.
+statistical properties.  So to ensure that the same sequence is reproduced
+on a later Erlang/OTP release, use a `seed/2` or `seed_s/2` to select
+both a specific algorithm and the seed value.
 
 #### Old Algorithms