Merge #532: Do trivial docs improvements

ecdad39 context: Improve rustdocs (Tobin C. Harding)
e945751 schnorr: Improve rustdocs (Tobin C. Harding)
47f19a7 Use lowercase for schnorr (Tobin C. Harding)
27b3e92 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 ecdad39

Tree-SHA512: 7466090325e02331f11e34cd38625541fbe8e642882afa6ddf2cf5d11ed669c7b2b48fd5b819915392760f4c6ef4ee460c2e622b3af648f99906c3ac408045d4

Author: apoelstra

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.

src/context.rs

@@ -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() }
     }
@@ -307,7 +307,7 @@ unsafe impl<'buf> Context for AllPreallocated<'buf> {
 }
 
 impl<'buf, C: Context + 'buf> Secp256k1<C> {
-    /// 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<Secp256k1<C>, Error> {
         #[cfg(target_arch = "wasm32")]
         ffi::types::sanity_checks_for_wasm();
@@ -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.

src/ecdsa/mod.rs

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

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

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;
 

src/schnorr.rs

@@ -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,20 +119,20 @@ 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")))]
     pub fn sign_schnorr(&self, msg: &Message, keypair: &KeyPair) -> Signature {
         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,