Improve documentation

src/constants.rs

@@ -14,33 +14,33 @@
 //
 
 //! # Constants
-//! Constants related to the API and the underlying curve
+//! Constants related to the API and the underlying curve.
 
-/// The size (in bytes) of a message
+/// The size (in bytes) of a message.
 pub const MESSAGE_SIZE: usize = 32;
 
-/// The size (in bytes) of a secret key
+/// The size (in bytes) of a secret key.
 pub const SECRET_KEY_SIZE: usize = 32;
 
 /// The size (in bytes) of a serialized public key.
 pub const PUBLIC_KEY_SIZE: usize = 33;
 
-/// The size (in bytes) of an serialized uncompressed public key
+/// The size (in bytes) of an serialized uncompressed public key.
 pub const UNCOMPRESSED_PUBLIC_KEY_SIZE: usize = 65;
 
-/// The maximum size of a signature
+/// The maximum size of a signature.
 pub const MAX_SIGNATURE_SIZE: usize = 72;
 
-/// The maximum size of a compact signature
+/// The maximum size of a compact signature.
 pub const COMPACT_SIGNATURE_SIZE: usize = 64;
 
-/// Size of a Schnorr signature
+/// The size of a Schnorr signature.
 pub const SCHNORRSIG_SIGNATURE_SIZE: usize = 64;
 
-/// Size of a Schnorr public key
+/// The size of a Schnorr public key.
 pub const SCHNORRSIG_PUBLIC_KEY_SIZE: usize = 32;
 
-/// Size of a key pair
+/// The size of a key pair.
 pub const KEY_PAIR_SIZE: usize = 96;
 
 /// The Prime for the secp256k1 field element.
@@ -51,23 +51,23 @@ pub const FIELD_SIZE: [u8; 32] = [
     0xff, 0xff, 0xff, 0xfe, 0xff, 0xff, 0xfc, 0x2f
 ];
 
-/// The order of the secp256k1 curve
+/// The order of the secp256k1 curve.
 pub const CURVE_ORDER: [u8; 32] = [
     0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
     0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfe,
     0xba, 0xae, 0xdc, 0xe6, 0xaf, 0x48, 0xa0, 0x3b,
     0xbf, 0xd2, 0x5e, 0x8c, 0xd0, 0x36, 0x41, 0x41
 ];
 
-/// The X coordinate of the generator
+/// The X coordinate of the generator.
 pub const GENERATOR_X: [u8; 32] = [
     0x79, 0xbe, 0x66, 0x7e, 0xf9, 0xdc, 0xbb, 0xac,
     0x55, 0xa0, 0x62, 0x95, 0xce, 0x87, 0x0b, 0x07,
     0x02, 0x9b, 0xfc, 0xdb, 0x2d, 0xce, 0x28, 0xd9,
     0x59, 0xf2, 0x81, 0x5b, 0x16, 0xf8, 0x17, 0x98
 ];
 
-/// The Y coordinate of the generator
+/// The Y coordinate of the generator.
 pub const GENERATOR_Y: [u8; 32] = [
     0x48, 0x3a, 0xda, 0x77, 0x26, 0xa3, 0xc4, 0x65,
     0x5d, 0xa4, 0xfb, 0xfc, 0x0e, 0x11, 0x08, 0xa8,

src/context.rs

@@ -11,7 +11,7 @@ pub use self::alloc_only::*;
 
 #[cfg(all(feature = "global-context", feature = "std"))]
 #[cfg_attr(docsrs, doc(cfg(all(feature = "global-context", feature = "std"))))]
-/// Module implementing a singleton pattern for a global `Secp256k1` context
+/// Module implementing a singleton pattern for a global `Secp256k1` context.
 pub mod global {
     #[cfg(feature = "rand-std")]
     use rand;
@@ -20,7 +20,7 @@ pub mod global {
     use std::sync::Once;
     use {Secp256k1, All};
 
-    /// Proxy struct for global `SECP256K1` context
+    /// Proxy struct for global `SECP256K1` context.
     #[derive(Debug, Copy, Clone)]
     pub struct GlobalContext {
         __private: (),
@@ -60,8 +60,8 @@ pub mod global {
 }
 
 
-/// A trait for all kinds of Context's that lets you define the exact flags and a function to deallocate memory.
-/// It shouldn't be possible to implement this for types outside this crate.
+/// A trait for all kinds of contexts that lets you define the exact flags and a function to
+/// deallocate memory. It shouldn't be possible to implement this for types outside this crate.
 pub unsafe trait Context : private::Sealed {
     /// Flags for the ffi.
     const FLAGS: c_uint;
@@ -98,8 +98,8 @@ pub struct AllPreallocated<'buf> {
 mod private {
     use super::*;
     // A trick to prevent users from implementing a trait.
-    // on one hand this trait is public, on the other it's in a private module
-    // so it's not visible to anyone besides it's parent (the context module)
+    // On one hand this trait is public, on the other it's in a private module
+    // so it's not visible to anyone besides it's parent (the context module).
     pub trait Sealed {}
 
     impl<'buf> Sealed for AllPreallocated<'buf> {}
@@ -289,7 +289,7 @@ unsafe impl<'buf> Context for VerifyOnlyPreallocated<'buf> {
     const DESCRIPTION: &'static str = "verification only";
 
     unsafe fn deallocate(_ptr: *mut u8, _size: usize) {
-        // Allocated by the user
+        // Allocated by the user.
     }
 }
 
@@ -298,7 +298,7 @@ unsafe impl<'buf> Context for AllPreallocated<'buf> {
     const DESCRIPTION: &'static str = "all capabilities";
 
     unsafe fn deallocate(_ptr: *mut u8, _size: usize) {
-        // Allocated by the user
+        // Allocated by the user.
     }
 }
 
@@ -328,7 +328,7 @@ impl<'buf> Secp256k1<AllPreallocated<'buf>> {
     pub fn preallocated_new(buf: &'buf mut [AlignedType]) -> Result<Secp256k1<AllPreallocated<'buf>>, Error> {
         Secp256k1::preallocated_gen_new(buf)
     }
-    /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for a context
+    /// 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()
     }
@@ -354,12 +354,12 @@ impl<'buf> Secp256k1<AllPreallocated<'buf>> {
 }
 
 impl<'buf> Secp256k1<SignOnlyPreallocated<'buf>> {
-    /// Creates a new Secp256k1 context that can only be used for signing
+    /// Creates a new Secp256k1 context that can only be used for signing.
     pub fn preallocated_signing_only(buf: &'buf mut [AlignedType]) -> Result<Secp256k1<SignOnlyPreallocated<'buf>>, Error> {
         Secp256k1::preallocated_gen_new(buf)
     }
 
-    /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context
+    /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context.
     #[inline]
     pub fn preallocate_signing_size() -> usize {
         Self::preallocate_size_gen()
@@ -374,7 +374,7 @@ impl<'buf> Secp256k1<SignOnlyPreallocated<'buf>> {
     /// * The capabilities (All/SignOnly/VerifyOnly) of the context *must* match the flags passed to libsecp256k1
     /// when generating the context.
     /// * The user must handle the freeing of the context(using the correct functions) by himself.
-    /// * This list *is not* exhaustive, and any violation may lead to Undefined Behavior.,
+    /// * This list *is not* exhaustive, and any violation may lead to Undefined Behavior.
     ///
     pub unsafe fn from_raw_signining_only(raw_ctx: *mut ffi::Context) -> ManuallyDrop<Secp256k1<SignOnlyPreallocated<'buf>>> {
         ManuallyDrop::new(Secp256k1 {
@@ -391,7 +391,7 @@ impl<'buf> Secp256k1<VerifyOnlyPreallocated<'buf>> {
         Secp256k1::preallocated_gen_new(buf)
     }
 
-    /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context
+    /// Uses the ffi `secp256k1_context_preallocated_size` to check the memory size needed for the context.
     #[inline]
     pub fn preallocate_verification_size() -> usize {
         Self::preallocate_size_gen()
@@ -406,7 +406,7 @@ impl<'buf> Secp256k1<VerifyOnlyPreallocated<'buf>> {
     /// * The capabilities (All/SignOnly/VerifyOnly) of the context *must* match the flags passed to libsecp256k1
     /// when generating the context.
     /// * The user must handle the freeing of the context(using the correct functions) by himself.
-    /// * This list *is not* exhaustive, and any violation may lead to Undefined Behavior.,
+    /// * This list *is not* exhaustive, and any violation may lead to Undefined Behavior.
     ///
     pub unsafe fn from_raw_verification_only(raw_ctx: *mut ffi::Context) -> ManuallyDrop<Secp256k1<VerifyOnlyPreallocated<'buf>>> {
         ManuallyDrop::new(Secp256k1 {

src/ecdh.rs

@@ -13,7 +13,7 @@
 //
 
 //! # ECDH
-//! Support for shared secret computations
+//! Support for shared secret computations.
 //!
 
 use core::ptr;
@@ -54,35 +54,35 @@ impl_from_array_len!(SharedSecret, 256, (16 20 28 32 48 64 96 128 256));
 
 impl SharedSecret {
 
-    /// Create an empty SharedSecret
+    /// Creates an empty `SharedSecret`.
     pub(crate) fn empty() ->  SharedSecret {
         SharedSecret {
             data: [0u8; 256],
             len: 0,
         }
     }
 
-    /// Get a pointer to the underlying data with the specified capacity.
+    /// Gets a pointer to the underlying data with the specified capacity.
     pub(crate) fn get_data_mut_ptr(&mut self) -> *mut u8 {
         self.data.as_mut_ptr()
     }
 
-    /// Get the capacity of the underlying data buffer.
+    /// Gets the capacity of the underlying data buffer.
     pub fn capacity(&self) -> usize {
         self.data.len()
     }
 
-    /// Get the len of the used data.
+    /// Gets the len of the used data.
     pub fn len(&self) -> usize {
         self.len
     }
 
-    /// True if the underlying data buffer is empty.
+    /// Returns true if the underlying data buffer is empty.
     pub fn is_empty(&self) -> bool {
         self.data.is_empty()
     }
 
-    /// Set the length of the object.
+    /// Sets the length of the object.
     pub(crate) fn set_len(&mut self, len: usize) {
         debug_assert!(len <= self.data.len());
         self.len = len;
@@ -116,7 +116,7 @@ unsafe extern "C" fn c_callback(output: *mut c_uchar, x: *const c_uchar, y: *con
 }
 
 impl SharedSecret {
-    /// Creates a new shared secret from a pubkey and secret key
+    /// Creates a new shared secret from a pubkey and secret key.
     #[inline]
     pub fn new(point: &PublicKey, scalar: &SecretKey) -> SharedSecret {
         let mut ss = SharedSecret::empty();
@@ -138,7 +138,7 @@ impl SharedSecret {
     }
 
 
-    /// Creates a new shared secret from a pubkey and secret key with applied custom hash function
+    /// Creates a new shared secret from a pubkey and secret key with applied custom hash function.
     /// The custom hash function must be in the form of `fn(x: [u8;32], y: [u8;32]) -> SharedSecret`
     /// `SharedSecret` can be easily created via the `From` impl from arrays.
     /// # Examples

src/ecdsa/recovery.rs

@@ -25,11 +25,11 @@ use ffi::recovery as ffi;
 use super::*;
 use {Verification, Secp256k1, Signing, Message};
 
-/// A tag used for recovering the public key from a compact signature
+/// A tag used for recovering the public key from a compact signature.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub struct RecoveryId(i32);
 
-/// An ECDSA signature with a recovery ID for pubkey recovery
+/// An ECDSA signature with a recovery ID for pubkey recovery.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub struct RecoverableSignature(ffi::RecoverableSignature);
 
@@ -53,8 +53,7 @@ pub fn to_i32(self) -> i32 {
 impl RecoverableSignature {
     #[inline]
     /// Converts a compact-encoded byte slice to a signature. This
-    /// representation is nonstandard and defined by the libsecp256k1
-    /// library.
+    /// representation is nonstandard and defined by the libsecp256k1 library.
     pub fn from_compact(data: &[u8], recid: RecoveryId) -> Result<RecoverableSignature, Error> {
         if data.is_empty() {return Err(Error::InvalidSignature);}
 
@@ -77,20 +76,20 @@ impl RecoverableSignature {
         }
     }
 
-    /// Obtains a raw pointer suitable for use with FFI functions
+    /// Obtains a raw pointer suitable for use with FFI functions.
     #[inline]
     pub fn as_ptr(&self) -> *const ffi::RecoverableSignature {
         &self.0
     }
 
-    /// Obtains a raw mutable pointer suitable for use with FFI functions
+    /// Obtains a raw mutable pointer suitable for use with FFI functions.
     #[inline]
     pub fn as_mut_ptr(&mut self) -> *mut ffi::RecoverableSignature {
         &mut self.0
     }
 
     #[inline]
-    /// Serializes the recoverable signature in compact format
+    /// Serializes the recoverable signature in compact format.
     pub fn serialize_compact(&self) -> (RecoveryId, [u8; 64]) {
         let mut ret = [0u8; 64];
         let mut recid = 0i32;
@@ -107,7 +106,7 @@ impl RecoverableSignature {
     }
 
     /// Converts a recoverable signature to a non-recoverable one (this is needed
-    /// for verification
+    /// for verification).
     #[inline]
     pub fn to_standard(&self) -> Signature {
         unsafe {
@@ -135,7 +134,7 @@ impl CPtr for RecoverableSignature {
     }
 }
 
-/// Creates a new recoverable signature from a FFI one
+/// Creates a new recoverable signature from a FFI one.
 impl From<ffi::RecoverableSignature> for RecoverableSignature {
     #[inline]
     fn from(sig: ffi::RecoverableSignature) -> RecoverableSignature {
@@ -144,7 +143,7 @@ impl From<ffi::RecoverableSignature> for RecoverableSignature {
 }
 
 impl<C: Signing> Secp256k1<C> {
-    /// Constructs a signature for `msg` using the secret key `sk` and RFC6979 nonce
+    /// Constructs a signature for `msg` using the secret key `sk` and RFC6979 nonce.
     /// Requires a signing-capable context.
     #[deprecated(since = "0.21.0", note = "Use sign_ecdsa_recoverable instead.")]
     pub fn sign_recoverable(&self, msg: &Message, sk: &key::SecretKey) -> RecoverableSignature {

src/key.rs

@@ -57,7 +57,7 @@ impl str::FromStr for SecretKey {
     }
 }
 
-/// The number 1 encoded as a secret key
+/// The number 1 encoded as a secret key.
 pub const ONE_KEY: SecretKey = SecretKey([0, 0, 0, 0, 0, 0, 0, 0,
                                           0, 0, 0, 0, 0, 0, 0, 0,
                                           0, 0, 0, 0, 0, 0, 0, 0,
@@ -344,7 +344,7 @@ impl PublicKey {
         unsafe {
             let mut pk = ffi::PublicKey::new();
             // We can assume the return value because it's not possible to construct
-            // an invalid `SecretKey` without transmute trickery or something
+            // an invalid `SecretKey` without transmute trickery or something.
             let res = ffi::secp256k1_ec_pubkey_create(secp.ctx, &mut pk, sk.as_c_ptr());
             debug_assert_eq!(res, 1);
             PublicKey(pk)