Added documentation

FastRng/Double/IRandom.cs

@@ -5,8 +5,20 @@ using FastRng.Double.Distributions;
 
 namespace FastRng.Double
 {
+    /// <summary>
+    /// Interface for random number generators.
+    /// </summary>
     public interface IRandom : IDisposable
     {
+        /// <summary>
+        /// Returns a uniform distributed pseudo-random number from the interval (0,1].
+        /// This means, the result 0 is impossible, whereas 1 is possible.
+        /// </summary>
+        /// <remarks>
+        /// This method is thread-safe. You can consume numbers from the same generator
+        /// by using multiple threads at the same time. 
+        /// </remarks>
+        /// <param name="cancel">An optional cancellation token.</param>
         public ValueTask<double> GetUniform(CancellationToken cancel = default);
     }
 }

FastRng/Double/MathTools.cs

@@ -2,11 +2,18 @@ using System;
 
 namespace FastRng.Double
 {
+    /// <summary>
+    /// Provides some mathematical function, which are not available within in the .NET framework.
+    /// </summary>
     public static class MathTools
     {
         private static readonly double SQRT_2 = Math.Sqrt(2.0);
         private static readonly double SQRT_PI = Math.Sqrt(Math.PI);
         
+        /// <summary>
+        /// The mathematical gamma function.
+        /// </summary>
+        /// <param name="z">The value for which you want calculate gamma.</param>
         public static double Gamma(double z)
         {
             // Source: http://rosettacode.org/wiki/Gamma_function#Go
@@ -36,8 +43,17 @@ namespace FastRng.Double
             return MathTools.SQRT_2 * MathTools.SQRT_PI * Math.Pow(t, z - 0.5) * Math.Exp(-t) * x;
         }
         
+        /// <summary>
+        /// The mathematical factorial function for floating-point numbers.
+        /// </summary>
+        /// <param name="x">The value, for which you want to know the factorial.</param>
         public static double Factorial(double x) => MathTools.Gamma(x + 1.0);
 
+        /// <summary>
+        /// The mathematical factorial function for integer numbers.
+        /// </summary>
+        /// <param name="x">The value, for which you want to know the factorial.</param>
+        /// <exception cref="ArgumentOutOfRangeException">Throws, when x is greater than 20. Due to limitations of 64bit ulong type.</exception>
         public static ulong Factorial(uint x)
         {
             if (x > 20)
@@ -50,6 +66,12 @@ namespace FastRng.Double
             return accumulator;
         }
 
+        /// <summary>
+        /// The mathematical factorial function for integer numbers.
+        /// </summary>
+        /// <param name="x">The value, for which you want to know the factorial.</param>
+        /// <exception cref="ArgumentOutOfRangeException">Throws, when x is greater than 20. Due to limitations
+        /// of 64bit ulong type. Throws also, when x is less than 0.</exception>
         public static ulong Factorial(int x)
         {
             if(x < 0)

FastRng/Double/MultiThreadedRng.cs

@@ -68,6 +68,15 @@ namespace FastRng.Double
 
         #region Constructors
 
+        /// <summary>
+        /// Creates a multi-threaded random number generator.
+        /// </summary>
+        /// <remarks>
+        /// This constructor uses the user's current local time
+        /// to derive necessary parameters for the generator.
+        /// Thus, the results are depending on the time, where
+        /// the generator was created.
+        /// </remarks>
         public MultiThreadedRng()
         {
             //
@@ -81,6 +90,19 @@ namespace FastRng.Double
             this.StartProducerThreads();
         }
 
+        /// <summary>
+        /// Creates a multi-threaded random number generator.
+        /// </summary>
+        /// <remarks>
+        /// A multi-threaded random number generator created by this constructor is
+        /// deterministic. It's behaviour is not depending on the time of its creation.<br/><br/>
+        ///
+        /// <b>Please note:</b> Although the number generator and all distributions are deterministic,
+        /// the behavior of the consuming application might be non-deterministic. This is possible if
+        /// the application with multiple threads consumes the numbers. The scheduling of the threads
+        /// is up to the operating system and might not be predictable. 
+        /// </remarks>
+        /// <param name="seedU">A seed value to generate a deterministic generator.</param>
         public MultiThreadedRng(uint seedU)
         {
             this.mW = seedU;
@@ -88,6 +110,20 @@ namespace FastRng.Double
             this.StartProducerThreads();
         }
         
+        /// <summary>
+        /// Creates a multi-threaded random number generator.
+        /// </summary>
+        /// <remarks>
+        /// A multi-threaded random number generator created by this constructor is
+        /// deterministic. It's behaviour is not depending on the time of its creation.<br/><br/>
+        ///
+        /// <b>Please note:</b> Although the number generator and all distributions are deterministic,
+        /// the behavior of the consuming application might be non-deterministic. This is possible if
+        /// the application with multiple threads consumes the numbers. The scheduling of the threads
+        /// is up to the operating system and might not be predictable. 
+        /// </remarks>
+        /// <param name="seedU">The first seed value.</param>
+        /// <param name="seedV">The second seed value.</param>
         public MultiThreadedRng(uint seedU, uint seedV)
         {
             this.mW = seedU;
@@ -209,6 +245,15 @@ namespace FastRng.Double
 
         #region Implementing interface
 
+        /// <summary>
+        /// Returns a uniform distributed pseudo-random number from the interval (0,1].
+        /// This means, the result 0 is impossible, whereas 1 is possible.
+        /// </summary>
+        /// <remarks>
+        /// This method is thread-safe. You can consume numbers from the same generator
+        /// by using multiple threads at the same time. 
+        /// </remarks>
+        /// <param name="cancel">An optional cancellation token.</param>
         public async ValueTask<double> GetUniform(CancellationToken cancel = default)
         {
             while (!cancel.IsCancellationRequested)
@@ -301,6 +346,11 @@ namespace FastRng.Double
         
         private void StopProducer() => this.producerTokenSource.Cancel();
 
+        /// <summary>
+        /// Disposes this generator. It is important to dispose a generator,
+        /// when it is no longer needed. Otherwise, the background threads
+        /// are still running.
+        /// </summary>
         public void Dispose() => this.StopProducer();
 
         #endregion

FastRng/Double/ShapeFitter.cs

@@ -17,6 +17,12 @@ namespace FastRng.Double
         private readonly double sampleSize;
         private readonly IDistribution uniform;
 
+        /// <summary>
+        /// Creates a shape fitter instance.
+        /// </summary>
+        /// <param name="shapeFunction">The function which describes the desired shape.</param>
+        /// <param name="rng">The random number generator instance to use.</param>
+        /// <param name="sampleSize">The number of sampling steps to sample the given function.</param>
         public ShapeFitter(Func<double, double> shapeFunction, IRandom rng, ushort sampleSize = 50)
         {
             this.rng = rng;
@@ -39,6 +45,11 @@ namespace FastRng.Double
             this.max = maxValue;
         }
 
+        /// <summary>
+        /// Returns a random number regarding the given shape.
+        /// </summary>
+        /// <param name="token">An optional cancellation token.</param>
+        /// <returns>The next value regarding the given shape.</returns>
         public async ValueTask<double> NextNumber(CancellationToken token = default)
         {
             while (!token.IsCancellationRequested)

FastRng/Float/IRandom.cs

@@ -5,8 +5,20 @@ using FastRng.Float.Distributions;
 
 namespace FastRng.Float
 {
+    /// <summary>
+    /// Interface for random number generators.
+    /// </summary>
     public interface IRandom : IDisposable
     {
+        /// <summary>
+        /// Returns a uniform distributed pseudo-random number from the interval (0,1].
+        /// This means, the result 0 is impossible, whereas 1 is possible.
+        /// </summary>
+        /// <remarks>
+        /// This method is thread-safe. You can consume numbers from the same generator
+        /// by using multiple threads at the same time. 
+        /// </remarks>
+        /// <param name="cancel">An optional cancellation token.</param>
         public ValueTask<float> GetUniform(CancellationToken cancel = default);
     }
 }

FastRng/Float/MathTools.cs

@@ -2,11 +2,18 @@ using System;
 
 namespace FastRng.Float
 {
+    /// <summary>
+    /// Provides some mathematical function, which are not available within in the .NET framework.
+    /// </summary>
     public static class MathTools
     {
         private static readonly float SQRT_2 = MathF.Sqrt(2.0f);
         private static readonly float SQRT_PI = MathF.Sqrt(MathF.PI);
         
+        /// <summary>
+        /// The mathematical gamma function.
+        /// </summary>
+        /// <param name="z">The value for which you want calculate gamma.</param>
         public static float Gamma(float z)
         {
             // Source: http://rosettacode.org/wiki/Gamma_function#Go
@@ -36,8 +43,17 @@ namespace FastRng.Float
             return MathTools.SQRT_2 * MathTools.SQRT_PI * MathF.Pow(t, z - 0.5f) * MathF.Exp(-t) * x;
         }
         
+        /// <summary>
+        /// The mathematical factorial function for floating-point numbers.
+        /// </summary>
+        /// <param name="x">The value, for which you want to know the factorial.</param>
         public static float Factorial(float x) => MathTools.Gamma(x + 1.0f);
 
+        /// <summary>
+        /// The mathematical factorial function for integer numbers.
+        /// </summary>
+        /// <param name="x">The value, for which you want to know the factorial.</param>
+        /// <exception cref="ArgumentOutOfRangeException">Throws, when x is greater than 20. Due to limitations of 64bit ulong type.</exception>
         public static ulong Factorial(uint x)
         {
             if (x > 20)
@@ -50,6 +66,12 @@ namespace FastRng.Float
             return accumulator;
         }
 
+        /// <summary>
+        /// The mathematical factorial function for integer numbers.
+        /// </summary>
+        /// <param name="x">The value, for which you want to know the factorial.</param>
+        /// <exception cref="ArgumentOutOfRangeException">Throws, when x is greater than 20. Due to limitations
+        /// of 64bit ulong type. Throws also, when x is less than 0.</exception>
         public static ulong Factorial(int x)
         {
             if(x < 0)

FastRng/Float/MultiThreadedRng.cs

@@ -68,6 +68,15 @@ namespace FastRng.Float
 
         #region Constructors
 
+        /// <summary>
+        /// Creates a multi-threaded random number generator.
+        /// </summary>
+        /// <remarks>
+        /// This constructor uses the user's current local time
+        /// to derive necessary parameters for the generator.
+        /// Thus, the results are depending on the time, where
+        /// the generator was created.
+        /// </remarks>
         public MultiThreadedRng()
         {
             //
@@ -81,6 +90,19 @@ namespace FastRng.Float
             this.StartProducerThreads();
         }
 
+        /// <summary>
+        /// Creates a multi-threaded random number generator.
+        /// </summary>
+        /// <remarks>
+        /// A multi-threaded random number generator created by this constructor is
+        /// deterministic. It's behaviour is not depending on the time of its creation.<br/><br/>
+        ///
+        /// <b>Please note:</b> Although the number generator and all distributions are deterministic,
+        /// the behavior of the consuming application might be non-deterministic. This is possible if
+        /// the application with multiple threads consumes the numbers. The scheduling of the threads
+        /// is up to the operating system and might not be predictable. 
+        /// </remarks>
+        /// <param name="seedU">A seed value to generate a deterministic generator.</param>
         public MultiThreadedRng(uint seedU)
         {
             this.mW = seedU;
@@ -88,6 +110,20 @@ namespace FastRng.Float
             this.StartProducerThreads();
         }
         
+        /// <summary>
+        /// Creates a multi-threaded random number generator.
+        /// </summary>
+        /// <remarks>
+        /// A multi-threaded random number generator created by this constructor is
+        /// deterministic. It's behaviour is not depending on the time of its creation.<br/><br/>
+        ///
+        /// <b>Please note:</b> Although the number generator and all distributions are deterministic,
+        /// the behavior of the consuming application might be non-deterministic. This is possible if
+        /// the application with multiple threads consumes the numbers. The scheduling of the threads
+        /// is up to the operating system and might not be predictable. 
+        /// </remarks>
+        /// <param name="seedU">The first seed value.</param>
+        /// <param name="seedV">The second seed value.</param>
         public MultiThreadedRng(uint seedU, uint seedV)
         {
             this.mW = seedU;
@@ -209,6 +245,15 @@ namespace FastRng.Float
 
         #region Implementing interface
 
+        /// <summary>
+        /// Returns a uniform distributed pseudo-random number from the interval (0,1].
+        /// This means, the result 0 is impossible, whereas 1 is possible.
+        /// </summary>
+        /// <remarks>
+        /// This method is thread-safe. You can consume numbers from the same generator
+        /// by using multiple threads at the same time. 
+        /// </remarks>
+        /// <param name="cancel">An optional cancellation token.</param>
         public async ValueTask<float> GetUniform(CancellationToken cancel = default)
         {
             while (!cancel.IsCancellationRequested)
@@ -301,6 +346,11 @@ namespace FastRng.Float
         
         private void StopProducer() => this.producerTokenSource.Cancel();
 
+        /// <summary>
+        /// Disposes this generator. It is important to dispose a generator,
+        /// when it is no longer needed. Otherwise, the background threads
+        /// are still running.
+        /// </summary>
         public void Dispose() => this.StopProducer();
 
         #endregion

FastRng/Float/ShapeFitter.cs

@@ -16,6 +16,12 @@ namespace FastRng.Float
         private readonly float sampleSize;
         private readonly IDistribution uniform;
 
+        /// <summary>
+        /// Creates a shape fitter instance.
+        /// </summary>
+        /// <param name="shapeFunction">The function which describes the desired shape.</param>
+        /// <param name="rng">The random number generator instance to use.</param>
+        /// <param name="sampleSize">The number of sampling steps to sample the given function.</param>
         public ShapeFitter(Func<float, float> shapeFunction, IRandom rng, ushort sampleSize = 50)
         {
             this.rng = rng;
@@ -38,6 +44,11 @@ namespace FastRng.Float
             this.max = maxValue;
         }
 
+        /// <summary>
+        /// Returns a random number regarding the given shape.
+        /// </summary>
+        /// <param name="token">An optional cancellation token.</param>
+        /// <returns>The next value regarding the given shape.</returns>
         public async ValueTask<float> NextNumber(CancellationToken token = default)
         {
             while (!token.IsCancellationRequested)