[m-rev.] for review: library/random.m doc update

[Julien Fischer]

Hi Mark,

On Tue, 21 Feb 2023, Mark Brown wrote:

> commit 44741b4b9c093d9c832f3adb5de7f8573088d081
> Author: Mark Brown <mark at mercurylang.org>
> Date:   Tue Feb 21 02:45:50 2023 +1100
>
>     Update library documentation.
>
>     library/random.m:
>         Add a guide for people implementing RNGs using this interface.
>
>         Other minor improvements.
> 
> diff --git a/library/random.m b/library/random.m
> index e23136d9e..0a610e532 100644
> --- a/library/random.m
> +++ b/library/random.m
> @@ -14,12 +14,12 @@
>  %
>  % The interfaces can be used in three styles:
>  %
> -%   - In the "ground" style, an instance of the random/1 typeclass is
> -%   passed through the code using 'in' and 'out' modes. This can be used
> -%   to generate random numbers, and since the value is ground it can also
> -%   easily be stored in larger data structures. The major drawback is that
> -%   generators in this style tend to be either fast or of good quality,
> -%   but not both.
> +%   - In the "ground" or "shared" style, an instance of the random/1
> +%   typeclass is passed through the code using 'in' and 'out' modes. This
> +%   value is used to generate random numbers, and since the value is
> +%   ground it can also easily be stored in larger data structures. The
> +%   major drawback of this style is that the generators tend to be either
> +%   fast or of good quality, but not both.
>  %
>  %   - In the "unique" style, the urandom/2 typeclass is used instead. Each
>  %   instance consists of a "params" type which is passed into the code
> @@ -29,7 +29,8 @@
>  %
>  %   - A generator can be attached to the I/O state. In this case, the
>  %   interface is the same as the unique style, with 'io' being used as
> -%   the unique state.
> +%   the unique state.  This is particularly convenient for use in code
> +%   where the I/O state is already being passed around.

Zoltan has been changing comments in the library so that there is only
one space after a full stop.  For consistency you should do the same here,
especially as that seems to be the case elsewhere in this module.

...

> +% Notes for RNG implementors:
> +%
> +% To implement a random number generator library using the interface
> +% defined in this module, an instance must be created for either the
> +% random/1 typeclass or the urandom/2 typeclass.  The choice depends on
> +% whether or not the implementation destructively updates its state: if
> +% so then the urandom/2 typeclass should be used as it provides the
> +% necessary unique modes.

I would make that into two separate sentences.

    The choice depends on ... updated its state.
    For implementations that do descuctively update their state, the urandom/2
    typeclass should ...

> +% For most RNGs, destructive update is desirable since the state can be
> +% quite large and it would be expensive to make a copy of the state for
> +% each number generated.  Destructive update is often achieved with the
> +% use of arrays, hance array-based implementations typically require

s/hance/hence/

> +% the use of urandom/2.  The compiler doesn't properly enforce this,
> +% however - see the warning at the start of array.m - so some care is
> +% required.  The sfc32 and sfc64 submodules demonstrate the use of arrays
> +% for the generator state.
> +%
> +% In some cases it may be acceptable to implement only the shared
> +% interface, for example if the state is small.  The sfc16 submodule
> +% provides an example of this.
> +%
> +% Generally, it is sufficient to provide an implementation for only
> +% one of the above two typeclasses.  As mentioned earlier, users can
> +% create instances of other typeclasses using the following predicates
> +% in this module:
> +%
> +%   make_urandom/3
> +%   make_io_random/4
> +%   make_io_urandom/5
> +%
> +% If an implementation of urandom_dup/1 is also provided, then the
> +% function make_shared_random/2 can be used to make a shared version
> +% which will copy the state after each call.  Care should be taken with
> +% this, however, as users may unintentionally consume large amounts of
> +% memory with its use.

It's probably worth mentioning that there are some further examples of
RNGs in extras/random.

That's fine otherwise.

Julien.