Document lower and upper limits of random functions.

It's a nightmare to have some operate x >= 0, some x > 0, some x < M, some x <= M.

1 files changed, 15 insertions, 1 deletions

diff --git a/crawl-ref/source/random.cc b/crawl-ref/source/random.cc
index 27614c0e07..60f134a0bf 100644
--- a/crawl-ref/source/random.cc
+++ b/crawl-ref/source/random.cc
@@ -3,12 +3,14 @@
 #include <math.h>
 #include "random.h"
 
+// [low, high]
 int random_range(int low, int high)
 {
     ASSERT(low <= high);
     return (low + random2(high - low + 1));
 }
 
+// [low, high]
 int random_range(int low, int high, int nrolls)
 {
     ASSERT(nrolls > 0);
@@ -93,6 +95,7 @@ int random_choose_weighted(int weight, int first, ...)
 #define UINT32_MAX ((uint32_t)(-1))
 #endif
 
+// [0, max)
 int random2(int max)
 {
     if (max <= 1)
@@ -110,12 +113,14 @@ int random2(int max)
     }
 }
 
+// [0, 1]
 bool coinflip(void)
 {
     return (static_cast<bool>(random2(2)));
 }
 
 // Returns random2(x) if random_factor is true, otherwise the mean.
+// [0, x)
 int maybe_random2(int x, bool random_factor)
 {
     if (x <= 1)
@@ -126,6 +131,7 @@ int maybe_random2(int x, bool random_factor)
         return (x / 2);
 }
 
+// [num, num*size]
 int maybe_roll_dice(int num, int size, bool random)
 {
     if (random)
@@ -134,6 +140,7 @@ int maybe_roll_dice(int num, int size, bool random)
         return ((num + num * size) / 2);
 }
 
+// [num, num*size]
 int roll_dice(int num, int size)
 {
     int ret = 0;
@@ -196,6 +203,7 @@ void scale_dice(dice_def &dice, int threshold)
 }
 
 // Calculates num/den and randomly adds one based on the remainder.
+// [floor(num/den), ceil(num/den)]
 int div_rand_round(int num, int den)
 {
     int rem = num % den;
@@ -205,6 +213,7 @@ int div_rand_round(int num, int den)
         return (num / den);
 }
 
+// [0, max)
 int bestroll(int max, int rolls)
 {
     int best = 0;
@@ -221,6 +230,7 @@ int bestroll(int max, int rolls)
 
 // random2avg() returns same mean value as random2() but with a lower variance
 // never use with rolls < 2 as that would be silly - use random2() instead {dlb}
+// [0, max)
 int random2avg(int max, int rolls)
 {
     int sum = random2(max);
@@ -234,6 +244,7 @@ int random2avg(int max, int rolls)
 // originally designed to randomise evasion -
 // values are slightly lowered near (max) and
 // approach an upper limit somewhere near (limit/2)
+// [0, max]
 int random2limit(int max, int limit)
 {
     int i;
@@ -254,6 +265,7 @@ int random2limit(int max, int limit)
 // representing the % chance of success.
 // This just evaluates all n trials, there is probably an efficient way of
 // doing this but I'm not much of a statistician. -CAO
+// [0, n_trials]
 int binomial_generator(unsigned n_trials, unsigned trial_prob)
 {
     int count = 0;
@@ -264,7 +276,7 @@ int binomial_generator(unsigned n_trials, unsigned trial_prob)
     return count;
 }
 
-// range [0..1)
+// range [0, 1.0)
 double random_real()
 {
     return random_int() / 4294967296.0;
@@ -272,6 +284,7 @@ double random_real()
 
 // Roll n_trials, return true if at least one succeeded.  n_trials might be
 // not integer.
+// [0, 1]
 bool bernoulli(double n_trials, double trial_prob)
 {
     if (n_trials <= 0 || trial_prob <= 0)
@@ -295,6 +308,7 @@ bool x_chance_in_y(int x, int y)
     return (random2(y) < x);
 }
 
+// [val - lowfuzz, val + highfuzz]
 int fuzz_value(int val, int lowfuzz, int highfuzz, int naverage)
 {
     const int lfuzz = lowfuzz * val / 100,