From 27b3e92889f435bbace043173cd93151113182bd Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 24 Nov 2022 11:13:45 +1100 Subject: [PATCH 1/4] Do trivial cleanup to module level docs Make the module level docs uniform across the codebase (style copied from rust-bitcoin). --- src/ecdsa/mod.rs | 1 + src/scalar.rs | 1 + src/schnorr.rs | 1 - 3 files changed, 2 insertions(+), 1 deletion(-) diff --git a/src/ecdsa/mod.rs b/src/ecdsa/mod.rs index 199bbae29..82aab7d30 100644 --- a/src/ecdsa/mod.rs +++ b/src/ecdsa/mod.rs @@ -1,4 +1,5 @@ //! Structs and functionality related to the ECDSA signature algorithm. +//! #[cfg(feature = "recovery")] mod recovery; diff --git a/src/scalar.rs b/src/scalar.rs index 190cbc044..80f54cb48 100644 --- a/src/scalar.rs +++ b/src/scalar.rs @@ -4,6 +4,7 @@ //! points. The most common type of scalars are private keys. However not all scalars are private //! keys. They can even be public *values*. To make handling them safer and easier this module //! provides the `Scalar` type and related. +//! use core::fmt; diff --git a/src/schnorr.rs b/src/schnorr.rs index a48420f36..0f464079a 100644 --- a/src/schnorr.rs +++ b/src/schnorr.rs @@ -1,4 +1,3 @@ -//! # schnorrsig //! Support for Schnorr signatures. //! From 47f19a78ef906374011520b5343f7f87631b8e27 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 24 Nov 2022 11:16:17 +1100 Subject: [PATCH 2/4] Use lowercase for schnorr In docs "schnorr signature" does not need, or deserve, a capital letter. --- src/constants.rs | 4 ++-- src/key.rs | 6 +++--- src/schnorr.rs | 8 ++++---- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/constants.rs b/src/constants.rs index f4563279e..4b506f998 100644 --- a/src/constants.rs +++ b/src/constants.rs @@ -34,10 +34,10 @@ pub const MAX_SIGNATURE_SIZE: usize = 72; /// The maximum size of a compact signature. pub const COMPACT_SIGNATURE_SIZE: usize = 64; -/// The size of a Schnorr signature. +/// The size of a schnorr signature. pub const SCHNORR_SIGNATURE_SIZE: usize = 64; -/// The size of a Schnorr public key. +/// The size of a schnorr public key. pub const SCHNORR_PUBLIC_KEY_SIZE: usize = 32; /// The size of a key pair. diff --git a/src/key.rs b/src/key.rs index b04b909fb..8aaf4db2d 100644 --- a/src/key.rs +++ b/src/key.rs @@ -1078,7 +1078,7 @@ 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 for verification of schnorr signatures and serialized according to BIP-340. /// /// # Serde support /// @@ -1165,7 +1165,7 @@ impl XOnlyPublicKey { } } - /// Creates a Schnorr public key directly from a slice. + /// Creates a schnorr public key directly from a slice. /// /// # Errors /// @@ -1472,7 +1472,7 @@ impl CPtr for XOnlyPublicKey { fn as_mut_c_ptr(&mut self) -> *mut Self::Target { &mut self.0 } } -/// Creates a new Schnorr public key from a FFI x-only public key. +/// Creates a new schnorr public key from a FFI x-only public key. impl From for XOnlyPublicKey { #[inline] fn from(pk: ffi::XOnlyPublicKey) -> XOnlyPublicKey { XOnlyPublicKey(pk) } diff --git a/src/schnorr.rs b/src/schnorr.rs index 0f464079a..c379308a7 100644 --- a/src/schnorr.rs +++ b/src/schnorr.rs @@ -1,4 +1,4 @@ -//! Support for Schnorr signatures. +//! Support for schnorr signatures. //! use core::{fmt, ptr, str}; @@ -14,7 +14,7 @@ use crate::{ constants, from_hex, impl_array_newtype, Error, Message, Secp256k1, Signing, Verification, }; -/// Represents a Schnorr signature. +/// Represents a schnorr signature. #[derive(Copy, Clone)] pub struct Signature([u8; constants::SCHNORR_SIGNATURE_SIZE]); impl_array_newtype!(Signature, u8, constants::SCHNORR_SIGNATURE_SIZE); @@ -132,7 +132,7 @@ impl Secp256k1 { self.sign_schnorr_helper(msg, keypair, ptr::null()) } - /// Create a Schnorr signature using the given auxiliary random data. + /// Create a schnorr signature using the given auxiliary random data. pub fn sign_schnorr_with_aux_rand( &self, msg: &Message, @@ -159,7 +159,7 @@ impl Secp256k1 { } impl Secp256k1 { - /// Verify a Schnorr signature. + /// Verify a schnorr signature. pub fn verify_schnorr( &self, sig: &Signature, From e945751d855d924c5e9af34661d8657289472155 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 24 Nov 2022 11:19:12 +1100 Subject: [PATCH 3/4] schnorr: Improve rustdocs Improve the rustdocs in the `schnorr` module by doing: - Use third person tense - Add full stops - Use links and code ticks --- src/schnorr.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/schnorr.rs b/src/schnorr.rs index c379308a7..cc748a6a1 100644 --- a/src/schnorr.rs +++ b/src/schnorr.rs @@ -73,7 +73,7 @@ impl str::FromStr for Signature { } impl Signature { - /// Creates a Signature directly from a slice + /// Creates a `Signature` directly from a slice. #[inline] pub fn from_slice(data: &[u8]) -> Result { match data.len() { @@ -119,7 +119,7 @@ impl Secp256k1 { } } - /// Create a schnorr signature internally using the ThreadRng random number + /// Creates a schnorr signature internally using the [`rand::rngs::ThreadRng`] random number /// generator to generate the auxiliary random data. #[cfg(feature = "rand-std")] #[cfg_attr(docsrs, doc(cfg(feature = "rand-std")))] @@ -127,12 +127,12 @@ impl Secp256k1 { self.sign_schnorr_with_rng(msg, keypair, &mut rand::thread_rng()) } - /// Create a schnorr signature without using any auxiliary random data. + /// Creates a schnorr signature without using any auxiliary random data. pub fn sign_schnorr_no_aux_rand(&self, msg: &Message, keypair: &KeyPair) -> Signature { self.sign_schnorr_helper(msg, keypair, ptr::null()) } - /// Create a schnorr signature using the given auxiliary random data. + /// Creates a schnorr signature using the given auxiliary random data. pub fn sign_schnorr_with_aux_rand( &self, msg: &Message, @@ -142,7 +142,7 @@ impl Secp256k1 { self.sign_schnorr_helper(msg, keypair, aux_rand.as_c_ptr() as *const ffi::types::c_uchar) } - /// Create a schnorr signature using the given random number generator to + /// Creates a schnorr signature using the given random number generator to /// generate the auxiliary random data. #[cfg(feature = "rand")] #[cfg_attr(docsrs, doc(cfg(feature = "rand")))] @@ -159,7 +159,7 @@ impl Secp256k1 { } impl Secp256k1 { - /// Verify a schnorr signature. + /// Verifies a schnorr signature. pub fn verify_schnorr( &self, sig: &Signature, From ecdad39ef48eef82e2fd5d67e8c700552e044256 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 24 Nov 2022 11:30:50 +1100 Subject: [PATCH 4/4] context: Improve rustdocs Improve the rustdocs in the `schnorr` module by doing: - Use third person tense - Add full stops - Use links and code ticks --- src/context.rs | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/src/context.rs b/src/context.rs index 937ae5d7d..8d958f7f7 100644 --- a/src/context.rs +++ b/src/context.rs @@ -71,10 +71,10 @@ pub unsafe trait Context: private::Sealed { unsafe fn deallocate(ptr: *mut u8, size: usize); } -/// Marker trait for indicating that an instance of `Secp256k1` can be used for signing. +/// Marker trait for indicating that an instance of [`Secp256k1`] can be used for signing. pub trait Signing: Context {} -/// Marker trait for indicating that an instance of `Secp256k1` can be used for verification. +/// 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 (preallocated memory). @@ -239,8 +239,8 @@ mod alloc_only { impl Secp256k1 { /// Creates a new Secp256k1 context that can only be used for verification. /// - /// If `rand-std` feature is enabled, context will have been randomized using `thread_rng`. - /// If `rand-std` feature is not enabled please consider randomizing the context (see docs + /// * If `rand-std` feature is enabled, context will have been randomized using `thread_rng`. + /// * If `rand-std` feature is not enabled please consider randomizing the context (see docs /// for `Secp256k1::gen_new()`). pub fn verification_only() -> Secp256k1 { Secp256k1::gen_new() } } @@ -299,7 +299,7 @@ unsafe impl<'buf> Context for AllPreallocated<'buf> { } impl<'buf, C: Context + 'buf> Secp256k1 { - /// Lets you create a context with a 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(); @@ -321,7 +321,7 @@ impl<'buf, C: Context + 'buf> Secp256k1 { } impl<'buf> Secp256k1> { - /// Creates a new Secp256k1 context with all capabilities + /// Creates a new Secp256k1 context with all capabilities. pub fn preallocated_new( buf: &'buf mut [AlignedType], ) -> Result>, Error> { @@ -330,7 +330,7 @@ impl<'buf> Secp256k1> { /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for a context. pub fn preallocate_size() -> usize { Self::preallocate_size_gen() } - /// Create a context from a raw context. + /// Creates a context from a raw context. /// /// # Safety /// This is highly unsafe, due to the number of conditions that aren't checked. @@ -364,9 +364,10 @@ impl<'buf> Secp256k1> { #[inline] pub fn preallocate_signing_size() -> usize { Self::preallocate_size_gen() } - /// Create a context from a raw context. + /// Creates a context from a raw context. /// /// # Safety + /// /// This is highly unsafe, due to the number of conditions that aren't checked. /// * `raw_ctx` needs to be a valid Secp256k1 context pointer. /// that was generated by *exactly* the same code/version of the libsecp256k1 used here. @@ -398,9 +399,10 @@ impl<'buf> Secp256k1> { #[inline] pub fn preallocate_verification_size() -> usize { Self::preallocate_size_gen() } - /// Create a context from a raw context. + /// Creates a context from a raw context. /// /// # Safety + /// /// This is highly unsafe, due to the number of conditions that aren't checked. /// * `raw_ctx` needs to be a valid Secp256k1 context pointer. /// that was generated by *exactly* the same code/version of the libsecp256k1 used here.