Compatible Doclog docs for library(random)
-:- module(random, [maybe/0, random/1, random_integer/3, set_random/1]).
+/**
+This library provides probabilistic predicates and random number generators.
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
To retain desirable declarative properties, predicates that internally
use random numbers should be equipped with an argument that specifies
the random seed. This makes everything completely reproducible.
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+*/
+
+:- module(random, [maybe/0, random/1, random_integer/3, set_random/1]).
:- use_module(library(error)).
-% succeeds with probability 0.5.
+%% maybe.
+%
+% Succeeds with probability 0.5.
maybe :- '$maybe'.
% The higher the precision, the slower it gets.
random_number_precision(64).
+%% random(-R).
+%
+% Generates a random floating number between 0 (inclusive) and 1 (exclusive).
random(R) :-
var(R),
random_number_precision(N),
rnd(N, R).
+%% random_integer(+Lower, +Upper, -R).
+%
+% Generates a random integer number between Lower (inclusive) and Upper (exclusive).
+%
+% Throws instantiation\_error if Lower or Upper are variables.
+%
+% Throws type\_error if Lower or Upper aren't integers.
random_integer(Lower, Upper, R) :-
var(R),
( (var(Lower) ; var(Upper)) ->
@@ -46,6 +60,10 @@ rnd_(N, R0, R) :-
R1 is R0 + 1.0 / 2.0 ^ N,
rnd_(N1, R1, R).
+%% set_random(+Seed).
+%
+% Sets a seed that will be used for subsequent random generations in this library.
+% It's necessary to set a seed to provide reproducible executions using this library.
set_random(Seed) :-
( nonvar(Seed) ->
( Seed = seed(S) ->
