docstrings and readme

README.md

@@ -4,6 +4,12 @@
 
 A set of extension methods for the .NET `System.Numerics.BigInteger` class, including methods like `BitCount`, `ModInverse`, `GenPseudoPrime`, `GenSafePseudoPrime`, `GenRandomBits` (using cryptographically strong RNG), `IsProbablePrime` (implemented using Rabin-Miller test).
 
+### Installation
+
+`Aprismatic.BigIntegerExt` library is available in GitHub package repo as well as on NuGet.org: <https://www.nuget.org/packages/Aprismatic.BigIntegerExt/>.
+
+You can install it through NuGet package manager in Visual Studion or Rider or run `dotnet add package Aprismatic.BigIntegerExt`.
+
 ### Usage
 
 ```csharp

src/Aprismatic.BigIntegerExt/Aprismatic.BigIntegerExt.csproj

@@ -1,6 +1,11 @@
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
     <TargetFrameworks>netstandard1.3;netstandard2.1</TargetFrameworks>
-    <Description>A set of extension methods for the .NET `System.Numerics.BigInteger` class, including methods like `ModInverse`, `GenPseudoPrime`, `GenRandomBits` (using cryptographically strong RNG), `IsProbablePrime` (implemented using Rabin-Miller test).</Description>
+    <Description>A set of extension methods for the .NET `System.Numerics.BigInteger` class, including methods like `BitCount`, `ModInverse`, `GenPseudoPrime`, `GenSafePseudoPrime`, `GenRandomBits` (using cryptographically strong RNG), `IsProbablePrime` (implemented using Rabin-Miller test). This library is provided free of charge under the MIT license. Contributions are welcome.</Description>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
-</Project>
+
+  <PropertyGroup>
+    <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>
+  </PropertyGroup>
+</Project>

src/Aprismatic.BigIntegerExt/BigIntegerExt.cs

@@ -15,15 +15,21 @@ [1] The MIT License (MIT), website, (http://opensource.org/licenses/MIT)
 
 namespace Aprismatic
 {
+    /// <summary>
+    /// A static class that provides extension methods for the BigInteger class,
+    /// including: <c>BitCount</c>, <c>ModInverse</c>, <c>GenPseudoPrime</c>,
+    /// <c>GenSafePseudoPrime</c>, <c>GenRandomBits</c>, and <c>IsProbablePrime</c>.
+    /// </summary>
     public static partial class BigIntegerExt
     {
         private static BigInteger Two = new BigInteger(2);
 
         /// <summary>
         /// Calculates the modulo inverse of `this`.
         /// </summary>
+        /// <param name="T">BigInteger to calculate modulo inverse of</param>
         /// <param name="mod">Modulo</param>
-        /// <returns>Modulo inverse of `this`; or 1 if mod.inv. does not exist.</returns>
+        /// <returns>Modulo inverse of `this`; or 1 if mod.inv. does not exist</returns>
         public static BigInteger ModInverse(this BigInteger T, BigInteger mod)
         {
             BigInteger i = mod, v = BigInteger.Zero, d = BigInteger.One, t, x;
@@ -80,6 +86,7 @@ public static int BitCount(this BigInteger T)
         /// The lower bound is inclusive, and the upper bound is exclusive.
         /// Code is based upon this StackOverflow answer: https://stackoverflow.com/a/68593532/664178
         /// </summary>
+        /// <param name="T">This parameter is irrelevant, required due to lack of static extension methods in C#</param>
         /// <param name="minValue">Inclusive lower bound</param>
         /// <param name="maxValue">Exclusive upper bound</param>
         /// <param name="rng">Random number generator to use</param>
@@ -114,6 +121,7 @@ public static BigInteger GenRandomBits(this BigInteger T, BigInteger minValue, B
         /// <summary>
         /// Returns a random BigInteger of exactly the specified bit length using the provided RNG
         /// </summary>
+        /// <param name="T">This parameter is irrelevant, required due to lack of static extension methods in C#</param>
         /// <param name="bits">Bit length of random BigInteger to generate</param>
         /// <param name="rng">RandomNumberGenerator object</param>
         /// <exception cref="ArgumentOutOfRangeException">`bits` must be > 0</exception>
@@ -159,6 +167,7 @@ public static BigInteger GenRandomBits(this BigInteger T, int bits, RandomNumber
         /// <summary>
         /// Generates a random probable prime positive BigInteger of exactly the specified bit length using the provided RNG
         /// </summary>
+        /// <param name="T">This parameter is irrelevant, required due to lack of static extension methods in C#</param>
         /// <param name="bits">Bit length of prime to generate; has to be greater than 1</param>
         /// <param name="confidence">Number of chosen bases</param>
         /// <param name="rng">RandomNumberGenerator object</param>
@@ -186,6 +195,7 @@ public static BigInteger GenPseudoPrime(this BigInteger T, int bits, int confide
         /// This method uses the Combined Sieve approach to improve performance as compared to naive algorithm.
         /// See Michael Wiener ``Safe Prime Generation with a Combined Sieve'', 2003 (https://eprint.iacr.org/2003/186)
         /// </summary>
+        /// <param name="T">This parameter is irrelevant, required due to lack of static extension methods in C#</param>
         /// <param name="bits">Bit length of prime to generate</param>
         /// <param name="confidence">Number of chosen bases</param>
         /// <param name="rng">RandomNumberGenerator object</param>
@@ -270,8 +280,9 @@ public static BigInteger GenSafePseudoPrime(this BigInteger T, int bits, int con
         /// </summary>
         /// <remarks>
         /// Before applying the test, the number is tested for divisibility by X first primes.
-        /// X was determined for different number of bits and is used as a constant.
+        /// Different amounts X were determined for different bit lengths and are used as a constant.
         /// </remarks>
+        /// <param name="T">BigInteger to check for primality</param>
         /// <param name="confidence">Number of chosen bases</param>
         /// <param name="rng">RandomNumberGenerator object</param>
         /// <param name="bitLength">Bit length of T (if not provided, the method calculates it)</param>
@@ -336,8 +347,8 @@ private static int PrimeFactorsToUse(int bitLength)
 
         /// <summary>
         /// Probabilistic prime test based on Miller-Rabin's algorithm.
-        /// Algorithm based on http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf (p. 72)
-        /// This method REQUIRES that the BigInteger is positive
+        /// Algorithm based on http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf (p. 72).
+        /// This method REQUIRES that the BigInteger is positive.
         /// </summary>
         /// <remarks>
         /// for any positive, odd p with p–1 = 2^s * t
@@ -348,7 +359,9 @@ private static int PrimeFactorsToUse(int bitLength)
         ///
         /// Otherwise, p is composite.
         /// </remarks>
+        /// <param name="w">BigInteger to check for primality</param>
         /// <param name="confidence">Number of rounds of RM algorithm to execute</param>
+        /// <param name="rng">RandomNumberGenerator object</param>
         /// <returns>True if this is a strong pseudoprime to randomly chosen bases</returns>
         public static bool RabinMillerTest(this BigInteger w, int confidence, RandomNumberGenerator rng)
         {

src/Aprismatic.BigIntegerExt/Primes.cs

@@ -5,7 +5,9 @@ namespace Aprismatic
 {
     public static partial class BigIntegerExt
     {
-        // primes smaller than 1M to test the generated prime number (https://www.mathematical.com/primes0to1000k.html)
+        /// <summary>
+        /// A list of primes smaller than 1M, source: https://www.mathematical.com/primes0to1000k.html
+        /// </summary>
         public static readonly ulong[] PrimesBelow1M =
         {
             2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97, 101,
@@ -7678,6 +7680,9 @@ public static partial class BigIntegerExt
             999931, 999953, 999959, 999961, 999979, 999983
         };
 
+        /// <summary>
+        /// A list of primes smaller than 1M converted to BigInteger type, source: https://www.mathematical.com/primes0to1000k.html
+        /// </summary>
         public static readonly BigInteger[] PrimesBelow1M_BI = PrimesBelow1M.Select(x => new BigInteger(x)).ToArray();
     }
 }