From 5ddd826f8ef27cb098579764286bdcd03b573562 Mon Sep 17 00:00:00 2001
From: siv2r <siv2ram@gmail.com>
Date: Wed, 5 Jan 2022 03:55:10 +0530
Subject: [PATCH] field.h: improve documentation for internal API's

- _fe_equal and _fe_equal_var requires the first input's magnitude to be 1
- _fe_equal_var requires only the first input magnitude to be 1
- mentioned pointer precondtions for _fe_mul and _fe_sqrt
- _fe_to_storage requires the input to be normalized
- add SECP256K1_RESTRICT for _fe_sqrt since, there is a VERIFY_CHECK(r != a)
in the func def. This is similar to the _fe_mul func.
---
 src/field.h      | 23 ++++++++++++++---------
 src/field_impl.h |  2 +-
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/src/field.h b/src/field.h
index 55679a2fc1..4840a81f40 100644
--- a/src/field.h
+++ b/src/field.h
@@ -64,10 +64,11 @@ static int secp256k1_fe_is_zero(const secp256k1_fe *a);
 /** Check the "oddness" of a field element. Requires the input to be normalized. */
 static int secp256k1_fe_is_odd(const secp256k1_fe *a);
 
-/** Compare two field elements. Requires magnitude-1 inputs. */
+/** Compare two field elements. Requires the first input to have magnitude equal to 1. */
 static int secp256k1_fe_equal(const secp256k1_fe *a, const secp256k1_fe *b);
 
-/** Same as secp256k1_fe_equal, but may be variable time. */
+/** Same as secp256k1_fe_equal, but may be variable time.
+ *  Requires the first input to have magnitude equal to 1. */
 static int secp256k1_fe_equal_var(const secp256k1_fe *a, const secp256k1_fe *b);
 
 /** Compare two field elements. Requires both inputs to be normalized */
@@ -91,6 +92,9 @@ static void secp256k1_fe_mul_int(secp256k1_fe *r, int a);
 static void secp256k1_fe_add(secp256k1_fe *r, const secp256k1_fe *a);
 
 /** Sets a field element to be the product of two others. Requires the inputs' magnitudes to be at most 8.
+ *  Preconditions for pointers passed:
+ *      1. Both input pointers (a, b) should not point to the same field object.
+ *      2. The second input pointer (b) and output pointer (r) should not point to same field object.
  *  The output magnitude is 1 (but not guaranteed to be normalized). */
 static void secp256k1_fe_mul(secp256k1_fe *r, const secp256k1_fe *a, const secp256k1_fe * SECP256K1_RESTRICT b);
 
@@ -98,12 +102,13 @@ static void secp256k1_fe_mul(secp256k1_fe *r, const secp256k1_fe *a, const secp2
  *  The output magnitude is 1 (but not guaranteed to be normalized). */
 static void secp256k1_fe_sqr(secp256k1_fe *r, const secp256k1_fe *a);
 
-/** If a has a square root, it is computed in r and 1 is returned. If a does not
- *  have a square root, the root of its negation is computed and 0 is returned.
- *  The input's magnitude can be at most 8. The output magnitude is 1 (but not
- *  guaranteed to be normalized). The result in r will always be a square
- *  itself. */
-static int secp256k1_fe_sqrt(secp256k1_fe *r, const secp256k1_fe *a);
+/** If a has a square root, it is computed in r and 1 is returned. If a does not have a square root, 
+ *  the root of its negation is computed and 0 is returned. The input's magnitude can be at most 8.
+ *  Preconditions for pointers passed:
+ *      1. Both input and output pointers (a, r) should not point to same field object.
+ *  The output magnitude is 1 (but not guaranteed to be normalized). 
+ *  The result in r will always be a square itself. */
+static int secp256k1_fe_sqrt(secp256k1_fe *r, const secp256k1_fe * SECP256K1_RESTRICT a);
 
 /** Sets a field element to be the (modular) inverse of another. Requires the input's magnitude to be
  *  at most 8. The output magnitude is 1 (but not guaranteed to be normalized). */
@@ -112,7 +117,7 @@ static void secp256k1_fe_inv(secp256k1_fe *r, const secp256k1_fe *a);
 /** Potentially faster version of secp256k1_fe_inv, without constant-time guarantee. */
 static void secp256k1_fe_inv_var(secp256k1_fe *r, const secp256k1_fe *a);
 
-/** Convert a field element to the storage type. */
+/** Convert a field element to the storage type. Requires the input to be normalized. */
 static void secp256k1_fe_to_storage(secp256k1_fe_storage *r, const secp256k1_fe *a);
 
 /** Convert a field element back from the storage type. */
diff --git a/src/field_impl.h b/src/field_impl.h
index 374284a1f4..ca04c2d04b 100644
--- a/src/field_impl.h
+++ b/src/field_impl.h
@@ -35,7 +35,7 @@ SECP256K1_INLINE static int secp256k1_fe_equal_var(const secp256k1_fe *a, const
     return secp256k1_fe_normalizes_to_zero_var(&na);
 }
 
-static int secp256k1_fe_sqrt(secp256k1_fe *r, const secp256k1_fe *a) {
+static int secp256k1_fe_sqrt(secp256k1_fe *r, const secp256k1_fe * SECP256K1_RESTRICT a) {
     /** Given that p is congruent to 3 mod 4, we can compute the square root of
      *  a mod p as the (p+1)/4'th power of a.
      *