Merge bitcoin-core/secp256k1#1347: field: Document return value of fe…

…_sqrt()

5779137 field: Document return value of fe_sqrt() (Tim Ruffing)

Pull request description:

ACKs for top commit:
  sipa:
    ACK 5779137
  theStack:
    ACK 5779137

Tree-SHA512: 706f8c6a26bf85f6c23af3bb053173b2cdee6838dd930cb2b1e2f851f47cfebafccecbd7d84b8152f2fea12f0676c1ddd700bb32beebec3f3e0f4300e878d0f5

src/field.h

@@ -267,8 +267,10 @@ static void secp256k1_fe_sqr(secp256k1_fe *r, const secp256k1_fe *a);
 /** Compute a square root of a field element.
  *
  * On input, a must be a valid field element with magnitude<=8; r need not be initialized.
- * Performs {r = sqrt(a)} or {r = sqrt(-a)}, whichever exists. The resulting value
- * represented by r will be a square itself. Variables r and a must not point to the same object.
+ * If sqrt(a) exists, performs {r = sqrt(a)} and returns 1.
+ * Otherwise, sqrt(-a) exists. The function performs {r = sqrt(-a)} and returns 0.
+ * The resulting value represented by r will be a square itself.
+ * Variables r and a must not point to the same object.
  * On output, r will have magnitude 1 but will not be normalized.
  */
 static int secp256k1_fe_sqrt(secp256k1_fe * SECP256K1_RESTRICT r, const secp256k1_fe * SECP256K1_RESTRICT a);