From fe550c2db3ede0cb5235d5918f1634358b56e5db Mon Sep 17 00:00:00 2001
From: fonsinchen <fonsinchen@openttd.org>
Date: Sun, 20 Oct 2013 14:48:08 +0000
Subject: (svn r25893) -Fix: Document RandomRange and change misleading
 parameter name 'max' in random functions.

---
 src/core/random_func.cpp | 15 ++++++++-------
 src/core/random_func.hpp | 21 ++++++++++++++-------
 2 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/src/core/random_func.cpp b/src/core/random_func.cpp
index 7800591e6..8cf21b54f 100644
--- a/src/core/random_func.cpp
+++ b/src/core/random_func.cpp
@@ -29,13 +29,14 @@ uint32 Randomizer::Next()
 }
 
 /**
- * Generate the next pseudo random number scaled to max
- * @param max the maximum value of the returned random number
- * @return the random number
+ * Generate the next pseudo random number scaled to \a limit, excluding \a limit
+ * itself.
+ * @param limit Limit of the range to be generated from.
+ * @return Random number in [0,\a limit)
  */
-uint32 Randomizer::Next(uint32 max)
+uint32 Randomizer::Next(uint32 limit)
 {
-	return ((uint64)this->Next() * (uint64)max) >> 32;
+	return ((uint64)this->Next() * (uint64)limit) >> 32;
 }
 
 /**
@@ -75,8 +76,8 @@ uint32 DoRandom(int line, const char *file)
 	return _random.Next();
 }
 
-uint32 DoRandomRange(uint32 max, int line, const char *file)
+uint32 DoRandomRange(uint32 limit, int line, const char *file)
 {
-	return ((uint64)DoRandom(line, file) * (uint64)max) >> 32;
+	return ((uint64)DoRandom(line, file) * (uint64)limit) >> 32;
 }
 #endif /* RANDOM_DEBUG */
diff --git a/src/core/random_func.hpp b/src/core/random_func.hpp
index e91413de2..0c6b8f1ca 100644
--- a/src/core/random_func.hpp
+++ b/src/core/random_func.hpp
@@ -25,7 +25,7 @@ struct Randomizer {
 	uint32 state[2];
 
 	uint32 Next();
-	uint32 Next(uint32 max);
+	uint32 Next(uint32 limit);
 	void SetSeed(uint32 seed);
 };
 extern Randomizer _random; ///< Random used in the game state calculations
@@ -65,17 +65,24 @@ void SetRandomSeed(uint32 seed);
 		#define Random() DoRandom(__LINE__, __FILE__)
 	#endif
 	uint32 DoRandom(int line, const char *file);
-	#define RandomRange(max) DoRandomRange(max, __LINE__, __FILE__)
-	uint32 DoRandomRange(uint32 max, int line, const char *file);
+	#define RandomRange(limit) DoRandomRange(limit, __LINE__, __FILE__)
+	uint32 DoRandomRange(uint32 limit, int line, const char *file);
 #else
 	static inline uint32 Random()
 	{
 		return _random.Next();
 	}
 
-	static inline uint32 RandomRange(uint32 max)
+	/**
+	 * Pick a random number between 0 and \a limit - 1, inclusive. That means 0
+	 * can be returned and \a limit - 1 can be returned, but \a limit can not be
+	 * returned.
+	 * @param limit Limit for the range to be picked from.
+	 * @return A random number in [0,\a limit).
+	 */
+	static inline uint32 RandomRange(uint32 limit)
 	{
-		return _random.Next(max);
+		return _random.Next(limit);
 	}
 #endif
 
@@ -84,9 +91,9 @@ static inline uint32 InteractiveRandom()
 	return _interactive_random.Next();
 }
 
-static inline uint32 InteractiveRandomRange(uint32 max)
+static inline uint32 InteractiveRandomRange(uint32 limit)
 {
-	return _interactive_random.Next(max);
+	return _interactive_random.Next(limit);
 }
 
 /**
-- 
cgit v1.2.3-54-g00ecf