Merge pull request #1648 from aarroyoc/docs-random

Compatible Doclog docs for library(random)

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.
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+*/
+
+:- 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) ->