Compatible Doclog docs for library(random)

diff --git a/src/lib/random.pl b/src/lib/random.pl
index d678aff23f1856f73869ee58f237e08970aa3511..15c35f3c3f1c8cedfbb4e8f21d633ec9f3cf097e 100644 (file)
--- a/src/lib/random.pl
+++ b/src/lib/random.pl
@@ -1,24 +1,38 @@
-:- 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.
+*/
 
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-   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) ->