Doxygenate the documentation in random.h

1 files changed, 28 insertions, 24 deletions

diff --git a/crawl-ref/source/random.h b/crawl-ref/source/random.h
index 7ebe261ed4..a00ddb9b44 100644
--- a/crawl-ref/source/random.h
+++ b/crawl-ref/source/random.h
@@ -27,8 +27,10 @@ bool bernoulli(double n_trials, double trial_prob);
 int fuzz_value(int val, int lowfuzz, int highfuzz, int naverage = 2);
 int roll_dice(int num, int size);
 
-// Chooses one of the numbers passed in at random. The list of numbers
-// must be terminated with -1.
+/**
+ * Chooses one of the numbers passed in at random. The list of numbers
+ * must be terminated with -1.
+ */
 template <typename T>
 T random_choose(T first, ...)
 {
@@ -101,28 +103,30 @@ public:
     ~rng_save_excursion()         { pop_rng_state(); }
 };
 
-// A defer_rand object represents an infinite tree of random values, allowing
-// for a much more functional approach to randomness.  defer_rand values which
-// have been used should not be copy-constructed.  Querying the same path
-// multiple times will always give the same result.
-
-// An important property of defer_rand is that, except for rounding,
-// float(r.random2(X)) / X == float(r.random2(Y)) / Y for all X and Y.  In
-// other words:
-//
-// * The parameter you use on any given call does not matter.
-// * The object stores the fraction, not a specific integer.
-// * random2() is monotonic in its argument.
-
-// Rephrased: The first time any node in the tree has a method called on
-// it, a random float between 0 and 1 (the fraction) is generated and stored,
-// and this float is combined with the method's parameters to arrive at
-// the result.  Calling the same method on the same node with the same
-// parameters will always give the same result, while different parameters
-// or methods will give different results (though they'll all use the same
-// float which was generated by the first method call).  Each node in the
-// tree has it's own float, so the same method+parameters on different
-// nodes will get different results.
+/**
+ * A defer_rand object represents an infinite tree of random values, allowing
+ * for a much more functional approach to randomness.  defer_rand values which
+ * have been used should not be copy-constructed.  Querying the same path
+ * multiple times will always give the same result.
+ *
+ * An important property of defer_rand is that, except for rounding,
+ * `float(r.random2(X)) / X == float(r.random2(Y)) / Y` for all `X` and `Y`.
+ * In other words:
+ *
+ * - The parameter you use on any given call does not matter.
+ * - The object stores the fraction, not a specific integer.
+ * - random2() is monotonic in its argument.
+ *
+ * Rephrased: The first time any node in the tree has a method called on
+ * it, a random float between 0 and 1 (the fraction) is generated and stored,
+ * and this float is combined with the method's parameters to arrive at
+ * the result.  Calling the same method on the same node with the same
+ * parameters will always give the same result, while different parameters
+ * or methods will give different results (though they'll all use the same
+ * float which was generated by the first method call).  Each node in the
+ * tree has it's own float, so the same method+parameters on different
+ * nodes will get different results.
+ */
 class defer_rand
 {
     vector<uint32_t> bits;