From 783b9107009384e8958a6a4a2a78577b333b5eb5 Mon Sep 17 00:00:00 2001
From: "W2.Wizard" <leon.delahamette@hotmail.de>
Date: Tue, 12 Jan 2021 20:29:32 +0100
Subject: [PATCH] Added XML comments

---
 Source/Engine/Core/Math/Randomf.cs | 94 +++++++++++++++++++++---------
 1 file changed, 67 insertions(+), 27 deletions(-)

diff --git a/Source/Engine/Core/Math/Randomf.cs b/Source/Engine/Core/Math/Randomf.cs
index 791de2cb8..9e25456ab 100644
--- a/Source/Engine/Core/Math/Randomf.cs
+++ b/Source/Engine/Core/Math/Randomf.cs
@@ -12,32 +12,44 @@ namespace FlaxEngine
         // Single instance for random
         private static Random _rand = new Random(0);
 
+        //TODO: Implement some form of generic method for numerics?
+
         /// <summary>
         /// Sets the seed of the random number generator.
-        /// Causes to construct a new <see cref="Random"/> instance.
+        /// Constructs a new <see cref="Random"/> instance.
         /// </summary>
-        /// <param name="newSeed">The new seed</param>
+        /// <param name="newSeed">The new seed.</param>
         public static void SetSeed(int newSeed) => _rand = new Random(newSeed);
 
-        // Bool
+        /// <summary>
+        /// Generates a random <see cref="bool"/>.
+        /// </summary>
+        /// <returns>A <see cref="bool"/> thats either true or false.</returns>
+        public static bool RandomBool() => RandomInt() == 1;
 
-        public static bool RandomBool()
-        {
-            return RandomInt() == 1 ? true : false;
-        }
-
-        public static bool RandomBoolWithWeight(float weight = 0)
-        {
-            return weight >= RandomInt() ? true : false;
-        }
-
-        // Byte
+        /// <summary>
+        /// Generates a random <see cref="bool"/> with a weight value to adjust preference.
+        /// </summary>
+        /// <param name="weight">Normalized value that determines the chance to return true.</param>
+        /// <returns>A <see cref="bool"/> thats either true or false.</returns>
+        public static bool RandomBoolWithWeight(float weight = 0) => weight >= RandomFloat();
 
+        /// <summary>
+        /// Generates a random <see cref="byte"/> value between min and max.
+        /// </summary>
+        /// <param name="min">The lower boundary.</param>
+        /// <param name="max">The upper boundary.</param>
+        /// <returns>A <see cref="byte"/> between min and max.</returns>
         public static byte RandomByte(byte min = 0, byte max = 1)
         {
             return (byte)_rand.Next(min, max+1);
         }
 
+        /// <summary>
+        /// Generates a random <see cref="byte"/> by using a single value as both upper and lower boundary.
+        /// </summary>
+        /// <param name="value">Defines both upper and lower boundary.</param>
+        /// <returns>A that is <see cref="byte"/> between +value and -value.</returns>
         public static byte RandomUniformByte(byte value = 1)
         {
             int max = Math.Abs(value);
@@ -46,13 +58,22 @@ namespace FlaxEngine
             return (byte)_rand.Next(min, max);
         }
 
-        // Int
-
+        /// <summary>
+        /// Generates a random <see cref="int"/> value between min and max.
+        /// </summary>
+        /// <param name="min">The lower boundary.</param>
+        /// <param name="max">The upper boundary.</param>
+        /// <returns>A random <see cref="int"/> between min and max.</returns>
         public static int RandomInt(int min = 0, int max = 1)
         {
             return _rand.Next(min, max+1);
         }
 
+        /// <summary>
+        /// Generates a random <see cref="int"/> by using a single value as both upper and lower boundary.
+        /// </summary>
+        /// <param name="value">Defines both upper and lower boundary.</param>
+        /// <returns>A random <see cref="int"/> between +value and -value.</returns>
         public static int RandomUniformInt(int value = 1)
         {
             int max = Math.Abs(value);
@@ -61,13 +82,22 @@ namespace FlaxEngine
             return _rand.Next(min, max);
         }
 
-        // Float
-
+        /// <summary>
+        /// Generates a random <see cref="float"/>  value between min and max.
+        /// </summary>
+        /// <param name="min">The lower boundary.</param>
+        /// <param name="max">The upper boundary.</param>
+        /// <returns>A random <see cref="float"/> between min and max.</returns>
         public static float RandomFloat(float min = 0.0f, float max = 1.0f)
         {
             return (float)_rand.NextDouble() * (max - min) + min;
         }
 
+        /// <summary>
+        /// Generates a random <see cref="float"/>  by using a single value as both upper and lower boundary.
+        /// </summary>
+        /// <param name="value">Defines both upper and lower boundary.</param>
+        /// <returns>A random <see cref="float"/>  between +value and -value.</returns>
         public static float RandomUniformFloat(float value = 1.0f)
         {
             // Ensure that in case of negative values we still return a value between + value and - value.
@@ -77,19 +107,22 @@ namespace FlaxEngine
             return (float)_rand.NextDouble() * (max - min) + min;
         }
 
-        // Quaternion
-
+        /// <summary>
+        /// Generates a random <see cref="Quaternion"/>.
+        /// </summary>
+        /// <returns>A random <see cref="Quaternion"/>.</returns>
         public static Quaternion RandomQuaternion()
         {
             return Quaternion.Euler(
                 RandomUniformFloat(180),
                 RandomUniformFloat(180),
-                RandomUniformFloat(180)
-                );
+                RandomUniformFloat(180));
         }
 
-        // Vector
-
+        /// <summary>
+        /// Generates a uniformly distributed random unit length vector point on a unit sphere.
+        /// </summary>
+        /// <returns>A random <see cref="Vector3"/>.</returns>
         public static Vector3 RandomVector3()
         {
             Vector3 output;
@@ -108,13 +141,16 @@ namespace FlaxEngine
             return output;
         }
 
+        /// <summary>
+        /// Generates a uniformly distributed random unit length vector point on a unit sphere in 2D.
+        /// </summary>
+        /// <returns>A random <see cref="Vector2"./></returns>
         public static Vector2 RandomVector2()
         {
             Vector2 output;
 
             do
             {
-                // Create random float with a mean of 0 and deviation of +-1;
                 output.X = RandomFloat() * 2.0f - 1.0f;
                 output.Y = RandomFloat() * 2.0f - 1.0f;
 
@@ -125,8 +161,12 @@ namespace FlaxEngine
             return output;
         }
 
-        // Color
-
+        /// <summary>
+        /// Generates a random color.
+        /// </summary>
+        /// <param name="trueRandom">Should the color be generated from a single random Hue value or separate values for each channel.</param>
+        /// <param name="randomAlpha">Randomize the alpha value.</param>
+        /// <returns>A nice random color.</returns>
         public static Color RandomColor(bool trueRandom, bool randomAlpha)
         {
             float alpha = randomAlpha ? RandomFloat() : 1f;