From 5a7cedef004412e37cf254f53018522d58ca9538 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 10 Nov 2022 11:38:45 +1100 Subject: [PATCH 1/3] doc: Fix preallocated memory grammar The grammar on structs that implement `Context` using preallocated memory is slightly incorrect. Attempt to improve the grammar. --- src/context.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/context.rs b/src/context.rs index 6e6851d..583c780 100644 --- a/src/context.rs +++ b/src/context.rs @@ -76,19 +76,19 @@ pub trait Signing: Context {} /// Marker trait for indicating that an instance of `Secp256k1` can be used for verification. pub trait Verification: Context {} -/// Represents the set of capabilities needed for signing with a user preallocated memory. +/// Represents the set of capabilities needed for signing (preallocated memory). #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct SignOnlyPreallocated<'buf> { phantom: PhantomData<&'buf ()>, } -/// Represents the set of capabilities needed for verification with a user preallocated memory. +/// Represents the set of capabilities needed for verification (preallocated memory). #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct VerifyOnlyPreallocated<'buf> { phantom: PhantomData<&'buf ()>, } -/// Represents the set of all capabilities with a user preallocated memory. +/// Represents the set of all capabilities (preallocated memory). #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct AllPreallocated<'buf> { phantom: PhantomData<&'buf ()>, @@ -301,7 +301,7 @@ unsafe impl<'buf> Context for AllPreallocated<'buf> { } impl<'buf, C: Context + 'buf> Secp256k1 { - /// Lets you create a context with preallocated buffer in a generic manner(sign/verify/all) + /// Lets you create a context with a preallocated buffer in a generic manner(sign/verify/all). pub fn preallocated_gen_new(buf: &'buf mut [AlignedType]) -> Result, Error> { #[cfg(target_arch = "wasm32")] ffi::types::sanity_checks_for_wasm(); From d546c161349fd3ccb17540c6abcc4005370efbb2 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 10 Nov 2022 11:43:08 +1100 Subject: [PATCH 2/3] Remove cfg docs feature requirements The `alloc_only` module already has a docs guard on the "alloc" feature, using an additional docs guard on the `SignOnly`, `VerifyOnly`, `All` enums leads to a redundant feature combination "alloc" and "alloc or std" - we really only require "alloc". --- src/context.rs | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/context.rs b/src/context.rs index 583c780..2f0fbe2 100644 --- a/src/context.rs +++ b/src/context.rs @@ -121,17 +121,14 @@ mod alloc_only { const ALIGN_TO: usize = core::mem::align_of::(); /// Represents the set of capabilities needed for signing. - #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum SignOnly {} /// Represents the set of capabilities needed for verification. - #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum VerifyOnly {} /// Represents the set of all capabilities. - #[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))] #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub enum All {} From ec47198a170afe395ce5227565ed0b52c4937883 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 10 Nov 2022 11:53:26 +1100 Subject: [PATCH 3/3] Remove ONE_KEY The `ONE_KEY` is only used in two rustdoc examples, as such it unnecessarily pollutes the crate root namespace. We can use `SecretKey::from_str()` with no loss of clarity and remove the `ONE_KEY`. While we are touching the import statements in `secret.rs` elect to remove the hide (use of `#`) for import statements relating to this library. Doing so gives devs all the information they need in one place if they are using the examples to copy code. It is also in line with the rest of the codebase. --- src/key.rs | 3 --- src/secret.rs | 13 +++++++------ 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/src/key.rs b/src/key.rs index 836dcec..410ebb8 100644 --- a/src/key.rs +++ b/src/key.rs @@ -74,9 +74,6 @@ impl str::FromStr for SecretKey { } } -/// The number 1 encoded as a secret key. -pub const ONE_KEY: SecretKey = SecretKey(constants::ONE); - /// A Secp256k1 public key, used for verification of signatures. /// /// # Serde support diff --git a/src/secret.rs b/src/secret.rs index 4ccd33d..dd2ffd4 100644 --- a/src/secret.rs +++ b/src/secret.rs @@ -118,7 +118,9 @@ impl SecretKey { /// /// ``` /// # #[cfg(feature = "std")] { - /// let key = secp256k1::ONE_KEY; + /// # use std::str::FromStr; + /// use secp256k1::SecretKey; + /// let key = SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001").unwrap(); /// /// // Normal debug hides value (`Display` is not implemented for `SecretKey`). /// // E.g., `format!("{:?}", key)` prints "SecretKey(#2518682f7819fb2d)". @@ -152,12 +154,11 @@ impl KeyPair { /// /// ``` /// # #[cfg(feature = "std")] { - /// use secp256k1::ONE_KEY; - /// use secp256k1::KeyPair; - /// use secp256k1::Secp256k1; + /// # use std::str::FromStr; + /// use secp256k1::{KeyPair, Secp256k1, SecretKey}; /// /// let secp = Secp256k1::new(); - /// let key = ONE_KEY; + /// let key = SecretKey::from_str("0000000000000000000000000000000000000000000000000000000000000001").unwrap(); /// let key = KeyPair::from_secret_key(&secp, &key); /// // Here we explicitly display the secret value: /// assert_eq!( @@ -190,7 +191,7 @@ impl SharedSecret { /// # #[cfg(not(fuzzing))] /// # #[cfg(feature = "std")] { /// # use std::str::FromStr; - /// # use secp256k1::{SecretKey, PublicKey}; + /// use secp256k1::{SecretKey, PublicKey}; /// use secp256k1::ecdh::SharedSecret; /// /// # let pk = PublicKey::from_slice(&[3, 23, 183, 225, 206, 31, 159, 148, 195, 42, 67, 115, 146, 41, 248, 140, 11, 3, 51, 41, 111, 180, 110, 143, 114, 134, 88, 73, 198, 174, 52, 184, 78]).expect("hard coded slice should parse correctly");