include usage advice about probabilistic predicates

diff --git a/src/prolog/lib/random.pl b/src/prolog/lib/random.pl
index 7e59fc23176abc6007a62c7ae065fe4cf06bae91..5fee57e0b086bebc6497912f0f671a15b1471d48 100644 (file)
--- a/src/prolog/lib/random.pl
+++ b/src/prolog/lib/random.pl
@@ -1,5 +1,11 @@
 :- module(random, [maybe/0, random/1, random_integer/3, set_random/1]).
 
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+   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.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+
 % succeeds with probability 0.5.
 maybe :- '$maybe'.