From e0fa21b24b376c480858eeb071abd51092924516 Mon Sep 17 00:00:00 2001
From: Tobin Harding <me@tobin.cc>
Date: Tue, 8 Mar 2022 12:01:55 +1100
Subject: [PATCH] Add rustdocs describing fixed width serde

We recently added fixed width serialization for some types however
serialization is only fixed width when data is serialized with the
`bincode` crate.

Add rustdocs describing fixed width serde to `SecretKey`, `PublicKey`,
and `XOnlyPublicKey` (`KeyPair` is already done).
---
 src/key.rs | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/src/key.rs b/src/key.rs
index e82862833..070e5b766 100644
--- a/src/key.rs
+++ b/src/key.rs
@@ -38,6 +38,12 @@ use schnorr;
 
 /// Secret 256-bit key used as `x` in an ECDSA signature.
 ///
+/// # Serde support
+///
+/// Implements de/serialization with the `serde` feature enabled. We treat the byte value as a tuple
+/// of 32 `u8`s for non-human-readable formats. This representation is optimal for for some formats
+/// (e.g. [`bincode`]) however other formats may be less optimal (e.g. [`cbor`]).
+///
 /// # Examples
 ///
 /// Basic usage:
@@ -50,6 +56,8 @@ use schnorr;
 /// let secret_key = SecretKey::new(&mut rand::thread_rng());
 /// # }
 /// ```
+/// [`bincode`]: https://docs.rs/bincode
+/// [`cbor`]: https://docs.rs/cbor
 pub struct SecretKey([u8; constants::SECRET_KEY_SIZE]);
 impl_array_newtype!(SecretKey, u8, constants::SECRET_KEY_SIZE);
 impl_display_secret!(SecretKey);
@@ -73,6 +81,12 @@ pub const ONE_KEY: SecretKey = SecretKey([0, 0, 0, 0, 0, 0, 0, 0,
 
 /// A Secp256k1 public key, used for verification of signatures.
 ///
+/// # Serde support
+///
+/// Implements de/serialization with the `serde` feature enabled. We treat the byte value as a tuple
+/// of 33 `u8`s for non-human-readable formats. This representation is optimal for for some formats
+/// (e.g. [`bincode`]) however other formats may be less optimal (e.g. [`cbor`]).
+///
 /// # Examples
 ///
 /// Basic usage:
@@ -86,6 +100,8 @@ pub const ONE_KEY: SecretKey = SecretKey([0, 0, 0, 0, 0, 0, 0, 0,
 /// let public_key = PublicKey::from_secret_key(&secp, &secret_key);
 /// # }
 /// ```
+/// [`bincode`]: https://docs.rs/bincode
+/// [`cbor`]: https://docs.rs/cbor
 #[derive(Copy, Clone, PartialEq, Eq, Debug, Hash)]
 #[repr(transparent)]
 pub struct PublicKey(ffi::PublicKey);
@@ -1041,6 +1057,12 @@ impl<'de> ::serde::Deserialize<'de> for KeyPair {
 
 /// An x-only public key, used for verification of Schnorr signatures and serialized according to BIP-340.
 ///
+/// # Serde support
+///
+/// Implements de/serialization with the `serde` feature enabled. We treat the byte value as a tuple
+/// of 32 `u8`s for non-human-readable formats. This representation is optimal for for some formats
+/// (e.g. [`bincode`]) however other formats may be less optimal (e.g. [`cbor`]).
+///
 /// # Examples
 ///
 /// Basic usage:
@@ -1054,6 +1076,8 @@ impl<'de> ::serde::Deserialize<'de> for KeyPair {
 /// let xonly = XOnlyPublicKey::from_keypair(&key_pair);
 /// # }
 /// ```
+/// [`bincode`]: https://docs.rs/bincode
+/// [`cbor`]: https://docs.rs/cbor
 #[derive(Copy, Clone, PartialEq, Eq, Debug, PartialOrd, Ord, Hash)]
 pub struct XOnlyPublicKey(ffi::XOnlyPublicKey);