Various changes to the random interface

Mostly stylistic changes. Cleaned up documentation.

Signed-off-by: Haru <haru@dotalux.com>

1 files changed, 61 insertions, 7 deletions

diff --git a/src/common/random.h b/src/common/random.h
index 41bdb4083..1b249ef19 100644
--- a/src/common/random.h
+++ b/src/common/random.h
@@ -23,25 +23,79 @@
 
 #include "common/hercules.h"
 
+/** @file
+ * The random number generator interface.
+ */
+
+/// Random interface.
 struct rnd_interface {
+	/**
+	 * Interface initialization.
+	 *
+	 * During initialization, the RNG is seeded with a random seed.
+	 */
 	void (*init) (void);
+
+	/// Interface finalization.
 	void (*final) (void);
 
-	void (*seed) (uint32);
+	/**
+	 * Re-seeds the random number generator.
+	 *
+	 * @param seed The new seed.
+	 */
+	void (*seed) (uint32 seed);
+
+	/**
+	 * Generates a random number in the interval [0, SINT32_MAX].
+	 */
+	int32 (*random) (void);
+
+	/**
+	 * Generates a random number in the interval [0, dice_faces).
+	 *
+	 * @remark
+	 *  interval is open ended, so dice_faces is excluded (unless it's 0)
+	 */
+	uint32 (*roll) (uint32 dice_faces);
 
-	int32 (*random) (void);// [0, SINT32_MAX]
-	uint32 (*roll) (uint32 dice_faces);// [0, dice_faces)
-	int32 (*value) (int32 min, int32 max);// [min, max]
-	double (*uniform) (void);// [0.0, 1.0)
-	double (*uniform53) (void);// [0.0, 1.0)
+	/**
+	 * Generates a random number in the interval [min, max].
+	 *
+	 * @retval min if range is invalid.
+	 */
+	int32 (*value) (int32 min, int32 max);
+
+	/**
+	 * Generates a random number in the interval [0.0, 1.0)
+	 *
+	 * @remark
+	 *  interval is open ended, so 1.0 is excluded
+	 */
+	double (*uniform) (void);
+
+	/**
+	 * Generates a random number in the interval [0.0, 1.0) with 53-bit resolution.
+	 *
+	 * 53 bits is the maximum precision of a double.
+	 *
+	 * @remark
+	 *   interval is open ended, so 1.0 is excluded
+	 */
+	double (*uniform53) (void);
 };
 
+/**
+ * Utlity macro to call the frequently used rnd_interface#random().
+ *
+ * @related rnd_interface.
+ */
 #define rnd() rnd->random()
 
 #ifdef HERCULES_CORE
 void rnd_defaults(void);
 #endif // HERCULES_CORE
 
-HPShared struct rnd_interface *rnd;
+HPShared struct rnd_interface *rnd; ///< Pointer to the random interface.
 
 #endif /* COMMON_RANDOM_H */