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

[Julien Fischer]

For review by anyone.

-------------------------------

Better document error behaviour in random.system_rng.

library/random.system_rng.m:
     Better document the error behaviour some predicates in this module.

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

     Adjust a comment.

Julien.

diff --git a/library/random.system_rng.m b/library/random.system_rng.m
index 0b1567e6e..1ddf18e48 100644
--- 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.
@@ -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). 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
+    % (see have_system_rng/0) or if a handle cannot be obtained (for example,
+    % because /dev/urandom could not be opened). Msg is a human-readable
+    % description of the error.
     %
 :- pred open_system_rng(maybe_error(system_rng)::out, io::di, io::uo)
     is det.
@@ -77,8 +86,15 @@

 %---------------------------------------------------------------------------%

-    % 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
+    % closed or if the underlying RNG cannot be read.
     %
 :- pred generate_uint8(system_rng::in, uint8::out, io::di, io::uo) is det.
 :- pred generate_uint16(system_rng::in, uint16::out, io::di, io::uo) is det.