diff: library/random.m documentation

[Fergus Henderson]

Hi Tom,

Can you please review this change?

library/random.m:
	Add documentation for the exported procedures.
	Declare the undocumented random__test predicate as
	`pragma obsolete' and remove it from the Mercury
	library reference manual (in preperation for
	deleting it in a future release).
	Some minor changes to the code to make it more
	readable.

Index: random.m
===================================================================
RCS file: /home/staff/zs/imp/mercury/library/random.m,v
retrieving revision 1.11
diff -u -r1.11 random.m
--- random.m	1997/05/21 02:16:20	1.11
+++ random.m	1997/06/20 10:52:19
@@ -21,24 +21,43 @@
 
 :- import_module list.
 
+	% The type `random__supply' represents a supply of random numbers.
 :- type random__supply.
 
+	% random__init(Seed, RS): creates a supply of random numbers RS
+	% using the specified Seed.
 :- pred random__init(int, random__supply).
 :- mode random__init(in, uo) is det.
 
+	% random__random(Num, RS0, RS): extracts a number Num in the
+	% range 0 .. RandMax from the random number supply RS0, and
+	% binds RS to the new state of the random number supply.
 :- pred random__random(int, random__supply, random__supply).
 :- mode random__random(out, mdi, muo) is det.
 
+	% random__randmax(RandMax, RS0, RS): binds Randax to the maximum
+	% random number that can be returned from the random number
+	% supply RS0, and returns RS = RS0.
 :- pred random__randmax(int, random__supply, random__supply).
 :- mode random__randmax(out, mdi, muo) is det.
 
+%---------------------------------------------------------------------------%
+
+:- implementation.
+	% Everything after the first `:- implementation' does not appear
+	% in the Mercury Library Reference Manual.
+:- interface.
+
+	% The following predicate was just for test purposes.
+	% It should not be used by user programs.
+:- pragma obolete random__test/4.
 :- pred random__test(int, int, list(int), int).
 :- mode random__test(in, in, out, out) is det.
 
 %---------------------------------------------------------------------------%
 
 :- implementation.
-:- import_module require, int.
+:- import_module int.
 
 :- type random__supply		==	int.	% I(j)
 
@@ -53,16 +72,12 @@
 random__random(I, RS0, RS) :-
 	RS0 = I0,
 	random__params(A, C, M),
-	I1 is I0 * A,
-	I2 is I1 + C,
-	I is I2 mod M,
+	I is ((I0 * A) + C) mod M,
 	copy(I, RS).
 
-random__randmax(M1, Rs0, Rs) :-
-	Rs0 = I,
+random__randmax(M1, Rs, Rs) :-
 	random__params(_A, _C, M),
-	M1 is M - 1,
-	Rs = I.
+	M1 is M - 1.
 
 %---------------------------------------------------------------------------%
 %---------------------------------------------------------------------------%

-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.