doc: clarify API doc of secp256k1_ecdsa_recover return value

Author: jonasnick

include/secp256k1_recovery.h

@@ -92,7 +92,15 @@ 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, when normalized,
+ *  passes `secp256k1_ecdsa_verify`. Thus, explicit verification is not necessary.
+ *
+ *  A recoverable signature converted to a normal signature may not pass
+ *  `secp256k1_ecdsa_verify` if it is not normalized. If a normalized signature is
+ *  required, call `secp256k1_ecdsa_signature_normalize` after
+ *  `secp256k1_ecdsa_recover`.
+ *
+ *  Returns: 1: public key successfully recovered
  *           0: otherwise.
  *  Args:    ctx:       pointer to a context object.
  *  Out:     pubkey:    pointer to the recovered public key.