From f764a7fb4c5ba89e9c82e2f629f757965d5fed75 Mon Sep 17 00:00:00 2001
From: "Tobin C. Harding" <me@tobin.cc>
Date: Wed, 9 Aug 2023 12:04:34 +1000
Subject: [PATCH] key: Improve docs

Crypto is _hard_. Make an effort to improve the docs with a minimum of
exactly correct information.
---
 src/key.rs | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/key.rs b/src/key.rs
index ecec1796f..4b4a6fa92 100644
--- a/src/key.rs
+++ b/src/key.rs
@@ -19,7 +19,9 @@ 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.
+///
+/// This value should be generated using a [cryptographically secure pseudorandom number generator].
 ///
 /// # Side channel attacks
 ///
@@ -48,6 +50,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 +118,7 @@ impl str::FromStr for SecretKey {
     }
 }
 
-/// A Secp256k1 public key, used for verification of signatures.
+/// Public key - used to verify ECDSA signatures, for ECDH handshakes, and to do Taproot tweaks.
 ///
 /// # Serde support
 ///
@@ -1070,7 +1073,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 - used to verify Taproot signatures.
+///
+/// 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
 ///