Update documentation for clarity.

diff --git a/src/assembly/fe.ts b/src/assembly/fe.ts
index a0c4e7f13684bfd1ac5b6782764c0ff23bab93c6..89b2092d2ca75baef94b4fe2bf228e78bd9b6ca3 100644 (file)
--- a/src/assembly/fe.ts
+++ b/src/assembly/fe.ts
@@ -247,7 +247,7 @@ const t1: FieldElement = fe()
 const t2: FieldElement = fe()
 const t3: FieldElement = fe()
 /**
- * Inversion - sets out to 0 if z=0
+ * Inversion - sets `out` = 0 if `z` == 0
  */
 export function fe_invert (out: FieldElement, z: FieldElement): void {
        fe_sq(t0, z)
@@ -302,7 +302,7 @@ const fe_isnegative_t = fe()
  * return 0 if f is in {0,2,4,...,q-1}
  *
  * Preconditions:
- * |f| bounded by 1.1*2²⁶,1.1*2²⁵,1.1*2²⁶,1.1*2²⁵,etc.
+ * |f| bounded by 1.1x2²⁶,1.1x2²⁵,1.1x2²⁶,1.1x2²⁵,etc.
  */
 //@ts-expect-error
 @inline
@@ -318,7 +318,7 @@ const fe_iszero_s = new StaticArray<u8>(32)
  * return 0 if f != 0
  *
  * Preconditions:
- * |f| bounded by 1.1*2^26,1.1*2^25,1.1*2^26,1.1*2^25,etc.
+ * |f| bounded by 1.1x2²⁶,1.1x2²⁵,1.1x2²⁶,1.1x2²⁵,etc.
  */
 //@ts-expect-error
 @inline
@@ -618,7 +618,7 @@ const fe_pow22523_t0: FieldElement = fe()
 const fe_pow22523_t1: FieldElement = fe()
 const fe_pow22523_t2: FieldElement = fe()
 /**
- * returns z^((p-5)/8) = z^(2^252-3)
+ * returns z^((p-5)/8) = z^(2²⁵²-3)
  * used to compute square roots since we have p=5 (mod 8); see Cohen and Frey.
  */
 export function fe_pow22523 (out: FieldElement, z: FieldElement): void {
@@ -673,16 +673,16 @@ export function fe_pow22523 (out: FieldElement, z: FieldElement): void {
 
 /**
  * Preconditions:
- * |h| bounded by 1.1*2²⁶,1.1*2²⁵,1.1*2²⁶,1.1*2²⁵,etc.
+ * |h| bounded by 1.1x2²⁶,1.1x2²⁵,1.1x2²⁶,1.1x2²⁵,etc.
  *
  * Write p=2²⁵⁵-19; q=floor(h/p).
- * Basic claim: q = floor(2⁻²⁵⁵(h + 19 2^(-25)h9 + 2^(-1))).
+ * Basic claim: q = floor(2⁻²⁵⁵(h + 19 2⁻²⁵h9 + 2⁻¹)).
  *
  * Proof:
  * Have |h|≤p so |q|≤1 so |19² 2⁻²⁵⁵ q|<1/4.
  * Also have |h-2²³⁰ h9|<2²³¹ so |19 2⁻²⁵⁵(h-2²³⁰ h9)|<1/4.
  *
- * Write y=2^(-1)-19² 2⁻²⁵⁵q-19 2⁻²⁵⁵(h-2²³⁰ h9).
+ * Write y=2⁻¹-19² 2⁻²⁵⁵q-19 2⁻²⁵⁵(h-2²³⁰ h9).
  * Then 0<y<1.
  *
  * Write r=h-pq.
@@ -692,8 +692,8 @@ export function fe_pow22523 (out: FieldElement, z: FieldElement): void {
  * Write x=r+19(2⁻²⁵⁵)r+y.
  * Then 0 < x < 2²⁵⁵ so floor(2⁻²⁵⁵x) = 0 so floor(q+2⁻²⁵⁵x) = q.
  *
- * Have q+2⁻²⁵⁵x = 2⁻²⁵⁵(h + 19 2^(-25) h9 + 2^(-1))
- * so floor(2⁻²⁵⁵(h + 19 2^(-25) h9 + 2^(-1))) = q.
+ * Have q+2⁻²⁵⁵x = 2⁻²⁵⁵(h + 19 2⁻²⁵ h9 + 2⁻¹)
+ * so floor(2⁻²⁵⁵(h + 19 2⁻²⁵ h9 + 2⁻¹)) = q.
  */
 export function fe_reduce (h: FieldElement, f: FieldElement): void {
        const f_ptr: usize = changetype<usize>(f)
@@ -791,10 +791,10 @@ export function fe_reduce (h: FieldElement, f: FieldElement): void {
  * Can overlap h with f.
  *
  * Preconditions:
- * |f| bounded by 1.65*2^26,1.65*2^25,1.65*2^26,1.65*2^25,etc.
+ * |f| bounded by 1.65*2²⁶,1.65*2²⁵,1.65*2²⁶,1.65*2²⁵,etc.
  *
  * Postconditions:
- * |h| bounded by 1.01*2^25,1.01*2^24,1.01*2^25,1.01*2^24,etc.
+ * |h| bounded by 1.01*2²⁵,1.01*2²⁴4,1.01*2²⁵,1.01*2²⁴,etc.
  *
  * @param h FieldElement power destination
  * @param f FieldElement base source
@@ -821,14 +821,14 @@ export function fe_sq (h: FieldElement, f: FieldElement): void {
        const f6_2: i64 = f6 * 2
        const f7_2: i64 = f7 * 2
 
-       const f5_19: i64 = f5 * 19 /* 1.959375*2^29 */
-       const f6_19: i64 = f6 * 19 /* 1.959375*2^30 */
-       const f7_19: i64 = f7 * 19 /* 1.959375*2^29 */
-       const f8_19: i64 = f8 * 19 /* 1.959375*2^30 */
-       const f9_19: i64 = f9 * 19 /* 1.959375*2^29 */
+       const f5_19: i64 = f5 * 19 /* 1.959375*2²⁹ */
+       const f6_19: i64 = f6 * 19 /* 1.959375*2³⁰ */
+       const f7_19: i64 = f7 * 19 /* 1.959375*2²⁹ */
+       const f8_19: i64 = f8 * 19 /* 1.959375*2³⁰ */
+       const f9_19: i64 = f9 * 19 /* 1.959375*2²⁹ */
 
-       const f7_38: i64 = f7 * 38 /* 1.959375*2^30 */
-       const f9_38: i64 = f9 * 38 /* 1.959375*2^30 */
+       const f7_38: i64 = f7 * 38 /* 1.959375*2³⁰ */
+       const f9_38: i64 = f9 * 38 /* 1.959375*2³⁰ */
 
        let h0: i64 = f0 * f0
        let h1: i64 = f0_2 * f1
@@ -984,10 +984,10 @@ export function fe_sq (h: FieldElement, f: FieldElement): void {
  * Can overlap h with f.
  *
  * Preconditions:
- * |f| bounded by 1.65*2^26,1.65*2^25,1.65*2^26,1.65*2^25,etc.
+ * |f| bounded by 1.65x2²⁶,1.65x2²⁵,1.65x2²⁶,1.65x2²⁵,etc.
  *
  * Postconditions:
- * |h| bounded by 1.01*2^25,1.01*2^24,1.01*2^25,1.01*2^24,etc.
+ * |h| bounded by 1.01x2²⁵,1.01x2²⁴,1.01x2²⁵,1.01x2²⁴,etc.
  *
  * @param hx FieldElement power destination
  * @param fx FieldElement base source
@@ -1007,11 +1007,11 @@ export function fe_sq_vec (hx: FieldElement, fx: FieldElement, hy: FieldElement,
        const f9: v128 = i32x4(load<i32>(fx_ptr, 36), load<i32>(fy_ptr, 36), 0, 0)
 
        const v19: v128 = i32x4.splat(19)
-       const f5_19: v128 = i32x4.mul(f5, v19) /* 1.959375*2^29 */
-       const f6_19: v128 = i32x4.mul(f6, v19) /* 1.959375*2^30 */
-       const f7_19: v128 = i32x4.mul(f7, v19) /* 1.959375*2^29 */
-       const f8_19: v128 = i32x4.mul(f8, v19) /* 1.959375*2^30 */
-       const f9_19: v128 = i32x4.mul(f9, v19) /* 1.959375*2^29 */
+       const f5_19: v128 = i32x4.mul(f5, v19) /* 1.959375*2²⁹ */
+       const f6_19: v128 = i32x4.mul(f6, v19) /* 1.959375*2³⁰ */
+       const f7_19: v128 = i32x4.mul(f7, v19) /* 1.959375*2²⁹ */
+       const f8_19: v128 = i32x4.mul(f8, v19) /* 1.959375*2³⁰ */
+       const f9_19: v128 = i32x4.mul(f9, v19) /* 1.959375*2²⁹ */
 
        // f[0]
        let f_2: v128 = i32x4.shl(f0, 1)