Merge rust-bitcoin/rust-secp256k1#532: Do trivial docs improvements

ecdad39ef4 context: Improve rustdocs (Tobin C. Harding)
e945751d85 schnorr: Improve rustdocs (Tobin C. Harding)
47f19a78ef Use lowercase for schnorr (Tobin C. Harding)
27b3e92889 Do trivial cleanup to module level docs (Tobin C. Harding)

Pull request description:

  Audit of docs in `rust-secp256k1` and do a few trivial fixes. The docs are in pretty good condition, they just need more content as described in #128 if that issue is still valid.

ACKs for top commit:
  apoelstra:
    ACK ecdad39ef4

Tree-SHA512: 7466090325e02331f11e34cd38625541fbe8e642882afa6ddf2cf5d11ed669c7b2b48fd5b819915392760f4c6ef4ee460c2e622b3af648f99906c3ac408045d4
This commit is contained in:
Andrew Poelstra 2022-11-24 14:16:25 +00:00
commit efb47e9bcf
No known key found for this signature in database
GPG Key ID: C588D63CE41B97C1
6 changed files with 26 additions and 23 deletions

View File

@ -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.

View File

@ -79,10 +79,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).
@ -247,8 +247,8 @@ mod alloc_only {
impl Secp256k1<VerifyOnly> {
/// 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<VerifyOnly> { Secp256k1::gen_new() }
}
@ -329,7 +329,7 @@ impl<'buf, C: Context + 'buf> Secp256k1<C> {
}
impl<'buf> Secp256k1<AllPreallocated<'buf>> {
/// 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<Secp256k1<AllPreallocated<'buf>>, Error> {
@ -338,7 +338,7 @@ impl<'buf> Secp256k1<AllPreallocated<'buf>> {
/// 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.
@ -372,9 +372,10 @@ impl<'buf> Secp256k1<SignOnlyPreallocated<'buf>> {
#[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.
@ -406,9 +407,10 @@ impl<'buf> Secp256k1<VerifyOnlyPreallocated<'buf>> {
#[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.

View File

@ -1,4 +1,5 @@
//! Structs and functionality related to the ECDSA signature algorithm.
//!
#[cfg(feature = "recovery")]
mod recovery;

View File

@ -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<ffi::XOnlyPublicKey> for XOnlyPublicKey {
#[inline]
fn from(pk: ffi::XOnlyPublicKey) -> XOnlyPublicKey { XOnlyPublicKey(pk) }

View File

@ -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;

View File

@ -1,5 +1,4 @@
//! # schnorrsig
//! Support for Schnorr signatures.
//! Support for schnorr signatures.
//!
use core::{fmt, ptr, str};
@ -15,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);
@ -74,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<Signature, Error> {
match data.len() {
@ -120,7 +119,7 @@ impl<C: Signing> Secp256k1<C> {
}
}
/// 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")))]
@ -128,12 +127,12 @@ impl<C: Signing> Secp256k1<C> {
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,
@ -143,7 +142,7 @@ impl<C: Signing> Secp256k1<C> {
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")))]
@ -160,7 +159,7 @@ impl<C: Signing> Secp256k1<C> {
}
impl<C: Verification> Secp256k1<C> {
/// Verify a Schnorr signature.
/// Verifies a schnorr signature.
pub fn verify_schnorr(
&self,
sig: &Signature,