key: Improve docs

Crypto is _hard_. Make an effort to improve the docs with a minimum of
exactly correct information.

src/key.rs

@@ -19,7 +19,12 @@ use crate::{ecdsa, SECP256K1};
 #[cfg(feature = "bitcoin_hashes")]
 use crate::{hashes, ThirtyTwoByteHash};
 
-/// Secret 256-bit key used as `x` in an ECDSA signature.
+/// Secret key - a 256-bit key used to create ECDSA and schnorr signatures.
+///
+/// A point on the secp256k1 curve i.e., a positive 256-bit integer guaranteed to be less than the
+/// secp256k1 curve order.
+///
+/// This value should be generated using a [cryptographically secure pseudorandom number generator].
 ///
 /// # Side channel attacks
 ///
@@ -48,6 +53,7 @@ use crate::{hashes, ThirtyTwoByteHash};
 /// ```
 /// [`bincode`]: https://docs.rs/bincode
 /// [`cbor`]: https://docs.rs/cbor
+/// [cryptographically secure pseudorandom number generator]: https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator
 #[derive(Copy, Clone)]
 pub struct SecretKey([u8; constants::SECRET_KEY_SIZE]);
 impl_display_secret!(SecretKey);
@@ -115,7 +121,9 @@ impl str::FromStr for SecretKey {
     }
 }
 
-/// A Secp256k1 public key, used for verification of signatures.
+/// Public key - a point on the secp256k1 curve.
+///
+/// Obtained by multiplying a secret key scalar by G (the generator point).
 ///
 /// # Serde support
 ///
@@ -1070,7 +1078,10 @@ impl CPtr for KeyPair {
     fn as_mut_c_ptr(&mut self) -> *mut Self::Target { &mut self.0 }
 }
 
-/// An x-only public key, used for verification of schnorr signatures and serialized according to BIP-340.
+/// An x-only public key - the X co-ordinate of a point on the secp256k1 curve.
+///
+/// To convert to a point (`PublicKey`) one must choose the [`Parity`] of the Y co-ordinate. When
+/// used to create schnorr signatures the Y co-ordinate is always positive.
 ///
 /// # Serde support
 ///