Merge #1741: doc: clarify API doc of secp256k1_ecdsa_recover return value

7321bdf doc: clarify API doc of `secp256k1_ecdsa_recover` return value (Jonas Nick)

Pull request description:

ACKs for top commit:
  jonasnick:
    ACK 7321bdf

Tree-SHA512: a7bac228cf504f6c8a53fdc15c7f3241ac27c214e10b9aabdf962e8d7c4c5107d0c0898467bd3f491cecf0ca2851c604da1ec5520a353b27c8aa02ce3daf2334

Author: jonasnick

include/secp256k1_recovery.h

@@ -92,7 +92,17 @@ SECP256K1_API int secp256k1_ecdsa_sign_recoverable(
 
 /** Recover an ECDSA public key from a signature.
  *
- *  Returns: 1: public key successfully recovered (which guarantees a correct signature).
+ *  Successful public key recovery guarantees that the signature, after normalization,
+ *  passes `secp256k1_ecdsa_verify`. Thus, explicit verification is not necessary.
+ *
+ *  However, a recoverable signature that successfully passes `secp256k1_ecdsa_recover`,
+ *  when converted to a non-recoverable signature (using
+ *  `secp256k1_ecdsa_recoverable_signature_convert`), is not guaranteed to be
+ *  normalized and thus not guaranteed to pass `secp256k1_ecdsa_verify`. If a
+ *  normalized signature is required, call `secp256k1_ecdsa_signature_normalize`
+ *  after `secp256k1_ecdsa_recoverable_signature_convert`.
+ *
+ *  Returns: 1: public key successfully recovered
  *           0: otherwise.
  *  Args:    ctx:       pointer to a context object.
  *  Out:     pubkey:    pointer to the recovered public key.