Merge #779: doc: Keypair constructors

aaf5fee fix: Invalid secret key (Christian Lewe)
d1d4ff9 doc: Keypair constructors accept odd keys (Christian Lewe)

Pull request description:

  Clarify the conditions when `Keypair` construction fails and correct the error variant that is returned in one of the constructors. Fixes #758

ACKs for top commit:
  Kixunil:
    ACK aaf5fee
  apoelstra:
    ACK aaf5fee; successfully ran local tests

Tree-SHA512: 9b27c4ee1424619f9041183801e7c1214838f0b8d529e9c10a3e1f55264624b6b42b881e369bd9521bfa117d3dd5ce072caed4b8ee51c40e1016fc5be59a2894

Author: apoelstra

src/key.rs

@@ -858,8 +858,8 @@ impl Keypair {
     ///
     /// # Errors
     ///
-    /// [`Error::InvalidSecretKey`] if the provided data has an incorrect length, exceeds Secp256k1
-    /// field `p` value or the corresponding public key is not even.
+    /// [`Error::InvalidSecretKey`] if the slice is not exactly 32 bytes long,
+    /// or if the encoded number exceeds the Secp256k1 field `p` value.
     #[inline]
     pub fn from_seckey_slice<C: Signing>(
         secp: &Secp256k1<C>,
@@ -883,22 +883,24 @@ impl Keypair {
     ///
     /// # Errors
     ///
-    /// [`Error::InvalidSecretKey`] if corresponding public key for the provided secret key is not even.
+    /// [`Error::InvalidSecretKey`] if the string does not consist of exactly 64 hex characters,
+    /// or if the encoded number exceeds the Secp256k1 field `p` value.
     #[inline]
     pub fn from_seckey_str<C: Signing>(secp: &Secp256k1<C>, s: &str) -> Result<Keypair, Error> {
         let mut res = [0u8; constants::SECRET_KEY_SIZE];
         match from_hex(s, &mut res) {
             Ok(constants::SECRET_KEY_SIZE) =>
                 Keypair::from_seckey_slice(secp, &res[0..constants::SECRET_KEY_SIZE]),
-            _ => Err(Error::InvalidPublicKey),
+            _ => Err(Error::InvalidSecretKey),
         }
     }
 
     /// Creates a [`Keypair`] directly from a secret key string and the global [`SECP256K1`] context.
     ///
     /// # Errors
     ///
-    /// [`Error::InvalidSecretKey`] if corresponding public key for the provided secret key is not even.
+    /// [`Error::InvalidSecretKey`] if the string does not consist of exactly 64 hex characters,
+    /// or if the encoded number exceeds the Secp256k1 field `p` value.
     #[inline]
     #[cfg(feature = "global-context")]
     pub fn from_seckey_str_global(s: &str) -> Result<Keypair, Error> {