Merge #340: Improve documentation

c73eb2f Use 'extra' instead of 'cheap' (Tobin Harding)
c79eb97 Remove unnecessary explanation (Tobin Harding)
f95e91a Use isn't instead of shouldn't (Tobin Harding)
c9e6ca1 Use rust-bitcoin module doc style (Tobin Harding)
3fa6762 Add link to referenced commit (Tobin Harding)
f5e68f3 Add ticks around code snippet (Tobin Harding)
d25431c Use 3rd person tense for function docs (Tobin Harding)
c3be285 Fix size constant docs (Tobin Harding)
5e07e75 Add period to sentences (Tobin Harding)
269bde0 Remove unnecessary capitalisation (Tobin Harding)

Pull request description:

  In a continued effort to find my feet around here, and inspired by issue #128 I've done a codebase wide audit of the docs (primarily just rustdocs but I glanced at `//` docs as well). Each change is in a separate commit so can be removed if resistance is met. (_"resistance is futile"_).

  I've based the stylistic decisions on [work done](rust-bitcoin/rust-bitcoin#704) in rust-bitcoin.

  I believe the only controversial change is the last (commit: da161c9 Use rust-bitcoin module doc style), please review that one carefully.

ACKs for top commit:
  apoelstra:
    ACK c73eb2f

Tree-SHA512: 5ea215de3fd23ca2a4f25d8f8d59a85a299044fe495269c43b621291ea50c58856fa8544e36cc109b7bdb1a7a59bcab8711f30113572ddce4509d3b06ff0d3b6

Author: apoelstra

src/constants.rs

@@ -13,34 +13,34 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # 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 isn't possible to implement this for types outside this crate.
 pub unsafe trait Context : private::Sealed {
     /// Flags for the ffi.
     const FLAGS: c_uint;
@@ -97,9 +97,6 @@ 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)
     pub trait Sealed {}
 
     impl<'buf> Sealed for AllPreallocated<'buf> {}
@@ -289,7 +286,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 +295,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 +325,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 +351,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 +371,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 +388,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 +403,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

@@ -12,8 +12,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # ECDH
-//! Support for shared secret computations
+//! Support for shared secret computations.
 //!
 
 use core::ptr;
@@ -54,35 +53,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 +115,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 +137,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

@@ -13,9 +13,9 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # Recovery module
 //! Provides a signing function that allows recovering the public key from the
 //! signature.
+//!
 
 use core::ptr;
 use key;
@@ -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 {
@@ -144,7 +143,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 {
@@ -153,7 +152,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

@@ -62,7 +62,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,
@@ -355,7 +355,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)