Improve comments

Author: AllFi

crypto/src/main/java/org/tron/common/crypto/zksnark/Fp.java

@@ -21,7 +21,8 @@
 
 /**
  * Arithmetic in F_p, p = 21888242871839275222246405745257275088696311157297823662689037894645226208583
- *
+ * This class stores elements of F_p in the Montgomery form: a*r mod p.
+ * 
  * @author Mikhail Kalinin
  * @since 01.09.2017
  */
@@ -32,40 +33,42 @@ public class Fp implements Field<Fp> {
   static final BigInteger P = new BigInteger(
       "21888242871839275222246405745257275088696311157297823662689037894645226208583");
 
-  /*
-   * 2^256
+  /**
+   * This value is equal to 2^256. It should be greater than {@link #P} and coprime to it.
+   * Field elements are represented in Montgomery form as a*{@link #REDUCER} mod {@link #P}. 
+   * This specific value of {@link #REDUCER} is selected to facilitate efficient division 
+   * by {@link #REDUCER} through simple shifting.
    */
   static final BigInteger REDUCER = new BigInteger(
     "115792089237316195423570985008687907853269984665640564039457584007913129639936");
 
+  /**
+   * The number of bits in the {@link #REDUCER} value.
+   */
   static final int REDUCER_BITS = 256;
 
-  /*
-   * REDUCER^2 mod P
+  /**
+   * A precomputed value of {@link #REDUCER}^2 mod {@link #P}.
    */
   static final BigInteger REDUCER_SQUARED = new BigInteger(
     "3096616502983703923843567936837374451735540968419076528771170197431451843209");
 
-  /*
-   * REDUCER^3 mod P
+  /**
+   * A precomputed value of {@link #REDUCER}^3 mod {@link #P}.
    */
   static final BigInteger REDUCER_CUBED = new BigInteger(
     "14921786541159648185948152738563080959093619838510245177710943249661917737183");
 
-  /*
-   * REDUCER^(-1) mod P
-   */
-  static final BigInteger RECIPROCAL = new BigInteger(
-    "20988524275117001072002809824448087578619730785600314334253784976379291040311");
-
-  /*
-   * -P^(-1) mod REDUCER
+  /**
+   * A precomputed value of -{@link #P}^{-1} mod {@link #REDUCER}.
    */
   static final BigInteger FACTOR = new BigInteger(
     "111032442853175714102588374283752698368366046808579839647964533820976443843465");
 
-  /*
-   * 2^256 - 1
+  /**
+   * The MASK value is set to 2^256 - 1 and is utilized to replace the operation % 2^256
+   * with a bitwise AND using this value. This choice ensures that only the lower 256 bits
+   * of a result are retained, effectively simulating the modulus operation.
    */
   static final BigInteger MASK = new BigInteger(
     "115792089237316195423570985008687907853269984665640564039457584007913129639935");
@@ -174,17 +177,35 @@ public String toString() {
     return v.toString();
   }
 
+  /**
+   * Converts a value in normal representation to Montgomery form.
+   * 
+   * @param n value in normal form
+   * @return value in Montgomery form
+   */
   private static BigInteger toMontgomery(BigInteger n) {
     return redc(n.multiply(REDUCER_SQUARED));
   }
 
+  /**
+   * Converts a value in Montgomery form to a normal representation.
+   * 
+   * @param n value in Montgomery form
+   * @return value in normal form
+   */
   private static BigInteger fromMontgomery(BigInteger n) {
     return redc(n);
   }
 
+  /**
+   * Montgomery reduction; given a value x, computes x*{@link #REDUCER}^{-1} mod {@link #P}
+   * 
+   * @param x value to reduce
+   * @return x*{@link #REDUCER}^{-1} mod {@link #P}
+   */
   private static BigInteger redc(BigInteger x)  {
     BigInteger temp = x.multiply(FACTOR).and(MASK);
-    BigInteger reduced = x.add(temp.multiply(P)).shiftRight(REDUCER_BITS);
+    BigInteger reduced = temp.multiply(P).add(x).shiftRight(REDUCER_BITS);
     return reduced.compareTo(P) < 0 ? reduced : reduced.subtract(P);
   }
 }