[m-rev.] for review: better document error behaviour in random.system_rng

[Zoltan Somogyi]

On Tue, 24 Feb 2026 15:17:48 +1100, Julien Fischer <jfischer at opturion.com> wrote:
> Better document error behaviour in random.system_rng.
>
> library/random.system_rng.m:
>      Better document the error behaviour some predicates in this module.

s/some/of some/
 
>      Adjust the header to comment to group the description of what happens
>      on Cygwin with the rest of the Windows description.

s/header to/header/

> --- a/library/random.system_rng.m
> +++ b/library/random.system_rng.m
> @@ -19,9 +19,10 @@
>  % of random material.
>  %
>  % On the C backends, the system RNG depends on the operating system.
> -% For macOS, Cygwin, OpenBSD, NetBSD and versions of FreeBSD from 12 onwards,
> -% we use the arc4random() family of functions.
> -% For Windows, we use the rand_s() function.
> +% For macOS, OpenBSD, NetBSD and versions of FreeBSD from 12 onwards, we use
> +% the arc4random() family of functions.
> +% For Windows, we use rand_s() from the Windows CRT; except when using Cygwin,
> +% where we use the arc4random() family of functions instead.
>  % For Linux, AIX, Solaris and versions of FreeBSD before 12, we read randomness
>  % from /dev/urandom; on these system each open system RNG handle will require
>  % an open file descriptor.

I would add blank lines between the groups of systems.

> @@ -63,7 +64,15 @@
> 
>      % open_system_rng(MaybeHandle, !IO):
>      %
> -    % Returns a handle through which the system RNG can be accessed.
> +    % Attempt to open a handle through which the system RNG can be accessed.
> +    % On success, returns ok(Handle).

s/returns/return/ (to fit with Attempt, not Attempts).

> The caller is responsible for releasing
> +    % the handle and any associated OS resources by calling close_system_rng/3
> +    % when it is no longer needed.
> +    %
> +    % Returns error(Msg) if the system RNG is not supported on this platform

Again, s/Returns/Return/

> +    % (see have_system_rng/0) or if a handle cannot be obtained (for example,
> +    % because /dev/urandom could not be opened).

I would format this as

- if abc
- if def

> Msg is a human-readable
> +    % description of the error.

I would put this as "Return error(Msg), where Msg is a human ..."

> -    % Generate a uniformly distributed unsigned integer of 8, 16, 32 or
> -    % 64 bits respectively using the system RNG.
> +    % generate_uint8(Handle, U8, !IO):
> +    % generate_uint16(Handle, U16, !IO):
> +    % generate_uint32(Handle, U32, !IO):
> +    % generate_uint64(Handle, U64, !IO):
> +    %
> +    % Generate a uniformly distributed unsigned integer of 8-, 16-, 32- or
> +    % 64-bits respectively using the system RNG accessed via Handle.
> +    % Throws an exception if an error occurs, for example if Handle has been

s/Throws/Throw/

Other than that, the diff seems fine, though I say that as someone who know
nothing about Windows APIs.

Zoltan.