Change `Rand_Next` to `u32`, document `rand.c` a bit more (#819)

* Change Rand_Next to u32, document rand.c a bit more

* Clean up the quotes a bit, add another note

* Format

* — -> -

* Review

* Remove unnecessary casts

* Remove quote, reformat the comments

* Fix new files

* Make docs a bit more consistent and specific

* Format

1 files changed, 36 insertions, 24 deletions

diff --git a/src/boot_O2/rand.c b/src/boot_O2/rand.c
index de603590e..2db64e9d5 100644
--- a/src/boot_O2/rand.c
+++ b/src/boot_O2/rand.c
@@ -1,33 +1,39 @@
 #include "global.h"
 
-// The latest generated random number, used to generate the next number in the sequence.
+//! The latest generated random number, used to generate the next number in the sequence.
 static u32 sRandInt = 1;
 
-// Space to store a value to be re-interpreted as a float.
-// This can't be static because it is used in z_kankyo
+//! Space to store a value to be re-interpreted as a float.
+//! This can't be static because it is used in z_kankyo.
 u32 sRandFloat;
 
+//! These values are recommended by the algorithms book *Numerical Recipes in C. The Art of Scientific Computing*, 2nd
+//! Edition, 1992, ISBN 0-521-43108-5. (p. 284):
+//! > This is about as good as any 32-bit linear congruential generator, entirely adequate for many uses.
 #define RAND_MULTIPLIER 1664525
 #define RAND_INCREMENT 1013904223
 
 /**
- * Gets the next integer in the sequence of pseudo-random numbers.
+ * Generates the next pseudo-random integer.
  */
-s32 Rand_Next(void) {
-    return sRandInt = (sRandInt * 1664525) + 1013904223;
+u32 Rand_Next(void) {
+    return sRandInt = (sRandInt * RAND_MULTIPLIER) + RAND_INCREMENT;
 }
 
 /**
- * Seeds the pseudo-random number generator by providing a starting value.
+ * Seeds the internal pseudo-random number generator with a provided starting value.
  */
 void Rand_Seed(u32 seed) {
     sRandInt = seed;
 }
 
 /**
- * Returns a pseudo-random floating-point number between 0.0f and 1.0f, by generating
- * the next integer and masking it to an IEEE-754 compliant floating-point number
- * between 1.0f and 2.0f, returning the result subtract 1.0f.
+ * Returns a pseudo-random float between 0.0f and 1.0f from the internal PRNG.
+ *
+ * @note Works by generating the next integer, masking it to an IEEE-754 compliant float between 1.0f and 2.0f, and
+ * subtracting 1.0f.
+ *
+ * @remark This is also recommended by Numerical Recipes, pp. 284-5.
  */
 f32 Rand_ZeroOne(void) {
     sRandInt = (sRandInt * RAND_MULTIPLIER) + RAND_INCREMENT;
@@ -36,8 +42,7 @@ f32 Rand_ZeroOne(void) {
 }
 
 /**
- * Returns a pseudo-random floating-point number between -0.5f and 0.5f by the same
- * manner in which Rand_ZeroOne generates its result.
+ * Returns a pseudo-random float between -0.5f and 0.5f in the same way as Rand_ZeroOne().
  */
 f32 Rand_Centered(void) {
     sRandInt = (sRandInt * RAND_MULTIPLIER) + RAND_INCREMENT;
@@ -45,40 +50,47 @@ f32 Rand_Centered(void) {
     return *((f32*)&sRandFloat) - 1.5f;
 }
 
+//! All functions below are unused variants of the above four, that use a provided random number variable instead of the
+//! internal `sRandInt`
+
 /**
- * Seeds a pseudo-random number at rndNum with a provided seed.
+ * Seeds a provided pseudo-random number with a provided starting value.
+ *
+ * @see Rand_Seed
  */
 void Rand_Seed_Variable(u32* rndNum, u32 seed) {
     *rndNum = seed;
 }
 
 /**
- * Generates the next pseudo-random integer from the provided rndNum.
+ * Generates the next pseudo-random number from the provided rndNum.
+ *
+ * @see Rand_Next
  */
 u32 Rand_Next_Variable(u32* rndNum) {
     return *rndNum = (*rndNum * RAND_MULTIPLIER) + RAND_INCREMENT;
 }
 
 /**
- * Generates the next pseudo-random floating-point number between 0.0f and
- * 1.0f from the provided rndNum.
+ * Generates the next pseudo-random float between 0.0f and 1.0f from the provided rndNum.
+ *
+ * @see Rand_ZeroOne
  */
 f32 Rand_ZeroOne_Variable(u32* rndNum) {
     u32 next = (*rndNum * RAND_MULTIPLIER) + RAND_INCREMENT;
-    // clang-format off
-    *rndNum = next; sRandFloat = (next >> 9) | 0x3F800000;
-    // clang-format on
+
+    sRandFloat = ((*rndNum = next) >> 9) | 0x3F800000;
     return *((f32*)&sRandFloat) - 1.0f;
 }
 
 /**
- * Generates the next pseudo-random floating-point number between -0.5f and
- * 0.5f from the provided rndNum.
+ * Generates the next pseudo-random float between -0.5f and 0.5f from the provided rndNum.
+ *
+ * @see Rand_ZeroOne, Rand_Centered
  */
 f32 Rand_Centered_Variable(u32* rndNum) {
     u32 next = (*rndNum * RAND_MULTIPLIER) + RAND_INCREMENT;
-    // clang-format off
-    *rndNum = next; sRandFloat = (next >> 9) | 0x3F800000;
-    // clang-format on
+
+    sRandFloat = ((*rndNum = next) >> 9) | 0x3F800000;
     return *((f32*)&sRandFloat) - 1.5f;
 }