f address some of pieter's comments

Author: jonasnick

include/secp256k1.h

@@ -447,7 +447,7 @@ SECP256K1_API int secp256k1_ecdsa_signature_serialize_compact(
 /** Verify an ECDSA signature.
  *
  *  Returns: 1: correct signature
- *           0: incorrect or unparseable signature
+ *           0: incorrect signature
  *  Args:    ctx:       a secp256k1 context object, initialized for verification.
  *  In:      sig:       the signature being verified (cannot be NULL)
  *           msg32:     the 32-byte message hash being verified (cannot be NULL)
@@ -524,9 +524,14 @@ SECP256K1_API int secp256k1_ecdsa_signature_normalize(
 SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_rfc6979;
 
 /** An implementation of the nonce generation function as defined in BIP-schnorr.
+ *
  * If a data pointer is passed, it is assumed to be a pointer to 32 bytes of
- * extra entropy. The attempt argument must be 0 or the function will fail and
- * return 0.
+ * extra entropy. If the data pointer is NULL and this function is used in
+ * schnorrsig_sign, it produces BIP-schnorr compliant signatures.
+ * When this function is used in ecdsa_sign, it generates a nonce using an
+ * analogue of the bip-schnorr nonce generation algorithm, but with tag
+ * "BIPSchnorrNULL" instead of "BIPSchnorrDerive".
+ * The attempt argument must be 0 or the function will fail and return 0.
  */
 SECP256K1_API extern const secp256k1_nonce_function secp256k1_nonce_function_bipschnorr;
 
@@ -710,10 +715,8 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ec_pubkey_combine(
 
 /** Opaque data structure that holds a parsed and valid "x-only" public key.
  *  An x-only pubkey encodes a positive point. That is a point whose Y
- *  coordinate is a quadratic residue. It is serialized using only its X
- *  coordinate (32 bytes). A secp256k1_xonly_pubkey is also a secp256k1_pubkey
- *  but the inverse is not true. Therefore, a secp256k1_pubkey must never be
- *  interpreted as or copied into a secp256k1_xonly_pubkey.
+ *  coordinate is square. It is serialized using only its X coordinate (32
+ *  bytes).
  *
  *  The exact representation of data inside is implementation defined and not
  *  guaranteed to be portable between different platforms or versions. It is
@@ -758,10 +761,8 @@ SECP256K1_API int secp256k1_xonly_pubkey_serialize(
     const secp256k1_xonly_pubkey* pubkey
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(3);
 
-/** Compute the xonly public key for a secret key. Just as ec_pubkey_create this
- *  function computes the point P by multiplying the seckey (interpreted as a scalar)
- *  with the generator. The public key corresponds to P if the Y coordinate of P is a
- *  quadratic residue or -P otherwise.
+/** Compute the xonly public key for a secret key. Same as ec_pubkey_create, but
+ *  for xonly public keys.
  *
  *  Returns: 1 if secret was valid, public key stores
  *           0 if secret was invalid, try again

include/secp256k1_schnorrsig.h

@@ -103,12 +103,11 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorrsig_verify(
  *
  *  Args:    ctx: a secp256k1 context object, initialized for verification.
  *       scratch: scratch space used for the multiexponentiation
- *  In:      sig: array of signatures, or NULL if there are no signatures
- *         msg32: array of messages, or NULL if there are no signatures
- *            pk: array of x-only public keys, or NULL if there are no signatures
- *        n_sigs: number of signatures in above arrays. Must be smaller than
- *                2^31 and smaller than half the maximum size_t value. Must be 0
- *                if above arrays are NULL.
+ *  In:      sig: array of pointers to signatures, or NULL if there are no signatures
+ *         msg32: array of pointers to messages, or NULL if there are no signatures
+ *            pk: array of pointers to x-only public keys, or NULL if there are no signatures
+ *        n_sigs: number of signatures in above arrays. Must be below the
+ *                minimum of 2^31 and SIZE_MAX/2. Must be 0 if above arrays are NULL.
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_schnorrsig_verify_batch(
     const secp256k1_context* ctx,

src/hash_impl.h

@@ -164,8 +164,7 @@ static void secp256k1_sha256_finalize(secp256k1_sha256 *hash, unsigned char *out
 }
 
 /* Initializes a sha256 struct and writes the 64 byte string
- * SHA256(tag)||SHA256(tag) into it. The taglen should be less than or equal to
- * 64. */
+ * SHA256(tag)||SHA256(tag) into it. */
 static void secp256k1_sha256_initialize_tagged(secp256k1_sha256 *hash, const unsigned char *tag, size_t taglen) {
     unsigned char buf[32];
     secp256k1_sha256_initialize(hash);

src/modules/schnorrsig/main_impl.h

@@ -83,10 +83,12 @@ int secp256k1_schnorrsig_sign(const secp256k1_context* ctx, secp256k1_schnorrsig
     }
 
     if (!noncefp(buf, msg32, seckey, (unsigned char *) "BIPSchnorrDerive", (void*)ndata, 0)) {
+        secp256k1_scalar_clear(&x);
         return 0;
     }
     secp256k1_scalar_set_b32(&k, buf, NULL);
     if (secp256k1_scalar_is_zero(&k)) {
+        secp256k1_scalar_clear(&x);
         return 0;
     }