Merge #145: Docs improvements

ddfd846 Audit rustdocs (Tobin Harding)
2d4a89e Improve module level docs (Tobin Harding)

Pull request description:

  Do crate wide docs improvements.

ACKs for top commit:
  apoelstra:
    ACK ddfd846

Tree-SHA512: 606bd5efae32472666c19c73e95f8cdefcf8ee55ab20b0dc44297f3de0da304c3b4285d20673268707af7f9b6b3718a9840f72489f287e5a6366b838ec7f4659

Author: apoelstra

src/cmp.rs

@@ -11,7 +11,7 @@
 /// volatile read. This should remain stable across compiler upgrades, but is much slower.
 ///
 /// As of rust 1.31.0 disassembly looks completely within reason for this, see
-/// https://godbolt.org/z/mMbGQv
+/// <https://godbolt.org/z/mMbGQv>.
 pub fn fixed_time_eq(a: &[u8], b: &[u8]) -> bool {
     assert!(a.len() == b.len());
     let count = a.len();

src/error.rs

@@ -12,12 +12,12 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # Error Type
+//! Crate error type.
 //!
 
 use core::fmt;
 
-/// [bitcoin_hashes] error.
+/// Crate error type.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Error {
     /// Tried to create a fixed-length hash from a slice with the wrong size (expected, got).

src/hash160.rs

@@ -17,7 +17,8 @@
 // was written entirely by Andrew Poelstra, who is re-licensing its
 // contents here as CC0.
 
-//! # HASH160 (SHA256 then RIPEMD160)
+//! HASH160 (SHA256 then RIPEMD160) implementation.
+//!
 
 use core::str;
 use core::ops::Index;
@@ -28,7 +29,7 @@ use ripemd160;
 use Hash as HashTrait;
 use Error;
 
-/// Output of the Bitcoin HASH160 hash function
+/// Output of the Bitcoin HASH160 hash function.
 #[derive(Copy, Clone, PartialEq, Eq, Default, PartialOrd, Ord, Hash)]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[repr(transparent)]

src/hex.rs

@@ -12,7 +12,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # Hex encoding and decoding
+//! Hex encoding and decoding.
 //!
 
 #[cfg(any(feature = "std", feature = "alloc"))]
@@ -28,14 +28,14 @@ use core2::io;
 use core::{fmt, str};
 use Hash;
 
-/// Hex decoding error
+/// Hex decoding error.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Error {
-    /// non-hexadecimal character
+    /// Non-hexadecimal character.
     InvalidChar(u8),
-    /// purported hex string had odd length
+    /// Purported hex string had odd length.
     OddLengthString(usize),
-    /// tried to parse fixed-length hash from a string with the wrong type (expected, got)
+    /// Tried to parse fixed-length hash from a string with the wrong type (expected, got).
     InvalidLength(usize, usize),
 }
 
@@ -49,29 +49,29 @@ impl fmt::Display for Error {
     }
 }
 
-/// Trait for objects that can be serialized as hex strings
+/// Trait for objects that can be serialized as hex strings.
 #[cfg(any(test, feature = "std", feature = "alloc"))]
 pub trait ToHex {
-    /// Hex representation of the object
+    /// Converts to a hexadecimal representation of the object.
     fn to_hex(&self) -> String;
 }
 
-/// Trait for objects that can be deserialized from hex strings
+/// Trait for objects that can be deserialized from hex strings.
 pub trait FromHex: Sized {
-    /// Produce an object from a byte iterator
+    /// Produces an object from a byte iterator.
     fn from_byte_iter<I>(iter: I) -> Result<Self, Error>
     where
         I: Iterator<Item = Result<u8, Error>> + ExactSizeIterator + DoubleEndedIterator;
 
-    /// Produce an object from a hex string
+    /// Produces an object from a hex string.
     fn from_hex(s: &str) -> Result<Self, Error> {
         Self::from_byte_iter(HexIterator::new(s)?)
     }
 }
 
 #[cfg(any(test, feature = "std", feature = "alloc"))]
 impl<T: fmt::LowerHex> ToHex for T {
-    /// Outputs the hash in hexadecimal form
+    /// Outputs the hash in hexadecimal form.
     fn to_hex(&self) -> String {
         format!("{:x}", self)
     }
@@ -100,8 +100,11 @@ pub struct HexIterator<'a> {
 }
 
 impl<'a> HexIterator<'a> {
-    /// Constructs a new `HexIterator` from a string slice. If the string is of
-    /// odd length it returns an error.
+    /// Constructs a new `HexIterator` from a string slice.
+    ///
+    /// # Errors
+    ///
+    /// If the input string is of odd length.
     pub fn new(s: &'a str) -> Result<HexIterator<'a>, Error> {
         if s.len() % 2 != 0 {
             Err(Error::OddLengthString(s.len()))
@@ -165,8 +168,9 @@ impl<'a> DoubleEndedIterator for HexIterator<'a> {
 
 impl<'a> ExactSizeIterator for HexIterator<'a> {}
 
-/// Output hex into an object implementing `fmt::Write`, which is usually more
-/// efficient than going through a `String` using `ToHex`.
+/// Outputs hex into an object implementing `fmt::Write`.
+///
+/// This is usually more efficient than going through a `String` using [`ToHex`].
 pub fn format_hex(data: &[u8], f: &mut fmt::Formatter) -> fmt::Result {
     let prec = f.precision().unwrap_or(2 * data.len());
     let width = f.width().unwrap_or(2 * data.len());
@@ -182,8 +186,9 @@ pub fn format_hex(data: &[u8], f: &mut fmt::Formatter) -> fmt::Result {
     Ok(())
 }
 
-/// Output hex in reverse order; used for Sha256dHash whose standard hex encoding
-/// has the bytes reversed.
+/// Outputs hex in reverse order.
+///
+/// Used for `sha256d::Hash` whose standard hex encoding has the bytes reversed.
 pub fn format_hex_reverse(data: &[u8], f: &mut fmt::Formatter) -> fmt::Result {
     let prec = f.precision().unwrap_or(2 * data.len());
     let width = f.width().unwrap_or(2 * data.len());

src/hmac.rs

@@ -17,7 +17,8 @@
 // was written entirely by Andrew Poelstra, who is re-licensing its
 // contents here as CC0.
 
-//! # HMAC support
+//! Hash-based Message Authentication Code (HMAC).
+//!
 
 use core::{borrow, fmt, ops, str};
 #[cfg(feature = "serde")]
@@ -41,16 +42,15 @@ impl<T: HashTrait + str::FromStr> str::FromStr for Hmac<T> {
     }
 }
 
-/// Pair of underlying hash midstates which represent the current state
-/// of an `HmacEngine`
+/// Pair of underlying hash midstates which represent the current state of an `HmacEngine`.
 pub struct HmacMidState<T: HashTrait> {
     /// Midstate of the inner hash engine
     pub inner: <T::Engine as EngineTrait>::MidState,
     /// Midstate of the outer hash engine
     pub outer: <T::Engine as EngineTrait>::MidState,
 }
 
-/// Pair of underyling hash engines, used for the inner and outer hash of HMAC
+/// Pair of underyling hash engines, used for the inner and outer hash of HMAC.
 #[derive(Clone)]
 pub struct HmacEngine<T: HashTrait> {
     iengine: T::Engine,
@@ -64,8 +64,13 @@ impl<T: HashTrait> Default for HmacEngine<T> {
 }
 
 impl<T: HashTrait> HmacEngine<T> {
-    /// Construct a new keyed HMAC with the given key. We only support underlying hashes
-    /// whose block sizes are ≤ 128 bytes; larger hashes will result in panics.
+    /// Constructs a new keyed HMAC from `key`.
+    ///
+    /// We only support underlying hashes whose block sizes are ≤ 128 bytes.
+    ///
+    /// # Panics
+    ///
+    /// Larger hashes will result in a panic.
     pub fn new(key: &[u8]) -> HmacEngine<T> {
         debug_assert!(T::Engine::BLOCK_SIZE <= 128);
 
@@ -98,8 +103,7 @@ impl<T: HashTrait> HmacEngine<T> {
         ret
     }
 
-    /// A special constructor giving direct access to the underlying
-    /// "inner" and "outer" engines.
+    /// A special constructor giving direct access to the underlying "inner" and "outer" engines.
     pub fn from_inner_engines(iengine: T::Engine, oengine: T::Engine) -> HmacEngine<T> {
         HmacEngine {
             iengine: iengine,

src/impls.rs

@@ -12,9 +12,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! `std` / `core2` Impls
+//! `std` / `core2` Impls.
+//!
+//! Implementations of traits defined in `std` / `core2` and not in `core`.
 //!
-//! impls of traits defined in `std` / `core2` and not in `core`
 
 #[cfg(feature = "std")]
 use std::{error, io};

src/lib.rs

@@ -12,7 +12,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # Rust Hashes Library
+//! Rust hashes library.
 //!
 //! This is a simple, no-dependency library which implements the hash functions
 //! needed by Bitcoin. These are SHA256, SHA256d, and RIPEMD160. As an ancillary
@@ -75,26 +75,26 @@ use core::{borrow, fmt, hash, ops};
 pub use hmac::{Hmac, HmacEngine};
 pub use error::Error;
 
-/// A hashing engine which bytes can be serialized into
+/// A hashing engine which bytes can be serialized into.
 pub trait HashEngine: Clone + Default {
-    /// Byte array representing the internal state of the hash engine
+    /// Byte array representing the internal state of the hash engine.
     type MidState;
 
     /// Outputs the midstate of the hash engine. This function should not be
     /// used directly unless you really know what you're doing.
     fn midstate(&self) -> Self::MidState;
 
-    /// Length of the hash's internal block size, in bytes
+    /// Length of the hash's internal block size, in bytes.
     const BLOCK_SIZE: usize;
 
-    /// Add data to the hash engine
+    /// Add data to the hash engine.
     fn input(&mut self, data: &[u8]);
 
-    /// Return the number of bytes already n_bytes_hashed(inputted)
+    /// Return the number of bytes already n_bytes_hashed(inputted).
     fn n_bytes_hashed(&self) -> usize;
 }
 
-/// Trait which applies to hashes of all types
+/// Trait which applies to hashes of all types.
 pub trait Hash: Copy + Clone + PartialEq + Eq + Default + PartialOrd + Ord +
     hash::Hash + fmt::Debug + fmt::Display + fmt::LowerHex +
     ops::Index<ops::RangeFull, Output = [u8]> +
@@ -109,24 +109,24 @@ pub trait Hash: Copy + Clone + PartialEq + Eq + Default + PartialOrd + Ord +
     /// any conditions.
     type Engine: HashEngine;
 
-    /// The byte array that represents the hash internally
+    /// The byte array that represents the hash internally.
     type Inner: hex::FromHex;
 
-    /// Construct a new engine
+    /// Constructs a new engine.
     fn engine() -> Self::Engine {
         Self::Engine::default()
     }
 
-    /// Produce a hash from the current state of a given engine
+    /// Produces a hash from the current state of a given engine.
     fn from_engine(e: Self::Engine) -> Self;
 
-    /// Length of the hash, in bytes
+    /// Length of the hash, in bytes.
     const LEN: usize;
 
-    /// Copies a byte slice into a hash object
+    /// Copies a byte slice into a hash object.
     fn from_slice(sl: &[u8]) -> Result<Self, Error>;
 
-    /// Hashes some bytes
+    /// Hashes some bytes.
     fn hash(data: &[u8]) -> Self {
         let mut engine = Self::engine();
         engine.input(data);
@@ -138,13 +138,13 @@ pub trait Hash: Copy + Clone + PartialEq + Eq + Default + PartialOrd + Ord +
     /// true for `Sha256dHash`, so here we are.
     const DISPLAY_BACKWARD: bool = false;
 
-    /// Unwraps the hash and returns the underlying byte array
+    /// Unwraps the hash and returns the underlying byte array.
     fn into_inner(self) -> Self::Inner;
 
-    /// Unwraps the hash and returns a reference to the underlying byte array
+    /// Unwraps the hash and returns a reference to the underlying byte array.
     fn as_inner(&self) -> &Self::Inner;
 
-    /// Constructs a hash from the underlying byte array
+    /// Constructs a hash from the underlying byte array.
     fn from_inner(inner: Self::Inner) -> Self;
 }
 

src/ripemd160.rs

@@ -17,7 +17,8 @@
 // was written entirely by Andrew Poelstra, who is re-licensing its
 // contents here as CC0.
 
-//! # RIPEMD160
+//! RIPEMD160 implementation.
+//!
 
 use core::{cmp, str};
 use core::ops::Index;
@@ -30,7 +31,7 @@ use util;
 
 const BLOCK_SIZE: usize = 64;
 
-/// Engine to compute RIPEMD160 hash function
+/// Engine to compute RIPEMD160 hash function.
 #[derive(Clone)]
 pub struct HashEngine {
     buffer: [u8; BLOCK_SIZE],
@@ -76,7 +77,7 @@ impl EngineTrait for HashEngine {
     engine_input_impl!();
 }
 
-/// Output of the RIPEMD160 hash function
+/// Output of the RIPEMD160 hash function.
 #[derive(Copy, Clone, PartialEq, Eq, Default, PartialOrd, Ord, Hash)]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 #[repr(transparent)]

src/serde_macros.rs

@@ -12,10 +12,11 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Macros for serde trait impls, and supporting code
+//! Macros for serde trait implementations, and supporting code.
+//!
 
 #[cfg(feature = "serde")]
-/// Functions used by serde impls of all hashes
+/// Functions used by serde impls of all hashes.
 pub mod serde_details {
     use Error;
 
@@ -82,7 +83,7 @@ pub mod serde_details {
         }
     }
 
-    /// Default serialization/deserialization methods
+    /// Default serialization/deserialization methods.
     pub trait SerdeHash
     where
         Self: Sized
@@ -92,13 +93,13 @@ pub mod serde_details {
             + ops::Index<ops::RangeFull, Output = [u8]>,
         <Self as FromStr>::Err: fmt::Display,
     {
-        /// Size, in bits, of the hash
+        /// Size, in bits, of the hash.
         const N: usize;
 
-        /// helper function to turn a deserialized slice into the correct hash type
+        /// Helper function to turn a deserialized slice into the correct hash type.
         fn from_slice_delegated(sl: &[u8]) -> Result<Self, Error>;
 
-        /// serde serialization
+        /// Do serde serialization.
         fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
             if s.is_human_readable() {
                 s.collect_str(self)
@@ -107,7 +108,7 @@ pub mod serde_details {
             }
         }
 
-        /// serde deserialization
+        /// Do serde deserialization.
         fn deserialize<'de, D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
             if d.is_human_readable() {
                 d.deserialize_str(HexVisitor::<Self>(PhantomData))
@@ -121,7 +122,7 @@ pub mod serde_details {
 #[macro_export]
 #[cfg(feature = "serde")]
 /// Implements `Serialize` and `Deserialize` for a type `$t` which
-/// represents a newtype over a byte-slice over length `$len`
+/// represents a newtype over a byte-slice over length `$len`.
 macro_rules! serde_impl(
     ($t:ident, $len:expr) => (
         impl $crate::serde_macros::serde_details::SerdeHash for $t {
@@ -144,7 +145,7 @@ macro_rules! serde_impl(
         }
 ));
 
-/// Does an "empty" serde implementation for the configuration without serde feature
+/// Does an "empty" serde implementation for the configuration without serde feature.
 #[macro_export]
 #[cfg(not(feature = "serde"))]
 macro_rules! serde_impl(