[RFE] More details in Lua 5.4.0 refman about random generator.

[Lorenzo Donati <lorenzodonatibz@...>]

Hi Lua Team!

I just noticed that one of the changes from Lua 5.3.0 was an improvement 
in random number generation.


The manual is a bit crypitc, besides saying:

"The results from this function have good statistical qualities, but 
they are not cryptographically secure. (For instance, there are no 
guarantees that it is hard to predict future results based on the 
observation of some previous results.) "


From an user POV, this doesn't tell much. I think that you should add
some more detail about the algorithm and the characteristics of the 
generator.

Otherwise a user could not tell if the built-in generator is good for 
their application, bar knowing it's no good for crypto stuff.

I suggest at least adding the (minimum) repetition period of the pseudo 
random sequences and some reference to the algorithm in literature.

In the sources it's written it is based on "xoshiro256". I think the 
manual should say that and maybe add some hint on the relevant (from the 
statistical properties POV) differences from the original algorithm (if 
any).

I think a few lines could suffice, like the following (just off the top 
of my head, but you get the point):

"The generator uses a variant of xoshiro256 algorithm. It has a 
guaranteed minimum repetition period of (2^256-1).
The modifications don't alter significantly the statistical properties 
of the original algorithm. For further info see the original xoshiro256 
documentation (http://prng.di.unimi.it/)."

Cheers!

-- Lorenzo