Merge #116: Do random improvements

30e7e48 Clean up comments in private error module (Tobin C. Harding)
7ea5793 embedded: Run formatter (Tobin C. Harding)
db157f9 Improve rustdoc (Tobin C. Harding)
e4f16cf Implement error traits for gf32::Error (Tobin C. Harding)
a2209d5 Remove crate level examples (Tobin C. Harding)
fdea41f Remove incorrect todo (Tobin C. Harding)
2fa4fc5 Add formatter to git pre-commit hook (Tobin C. Harding)

Pull request description:

  Pull all the unrelated random improvements out of #113 so that we can review/merge them more easily. Nothing controversial here except perhaps commit: `a2209d5 Remove crate level examples`. Note also that commit: `1a746b7 Clean up comments in private error module` is new.

ACKs for top commit:
  apoelstra:
    ACK 30e7e48

Tree-SHA512: 896a025d29659c7305a2fb1d524915fe628dfdb97158381216e50d203730955b4c6aa350dcf26c8a70b18e39cb61e024646ea1303f4bd20a5015b71a464397f4

Author: apoelstra

Diff for: embedded/no-allocator/src/main.rs

@@ -7,12 +7,11 @@
 #![no_main]
 #![no_std]
 
-use panic_halt as _;
-
 use arrayvec::{ArrayString, ArrayVec};
-use bech32::{self, u5, ComboError, FromBase32, ToBase32, Variant, Hrp};
+use bech32::{self, u5, ComboError, FromBase32, Hrp, ToBase32, Variant};
 use cortex_m_rt::entry;
 use cortex_m_semihosting::{debug, hprintln};
+use panic_halt as _;
 
 // Note: `#[global_allocator]` is NOT set.
 
@@ -26,9 +25,7 @@ fn main() -> ! {
 
     let hrp = Hrp::parse("bech32").unwrap();
 
-    bech32::encode_to_fmt_anycase(&mut encoded, hrp, &base32, Variant::Bech32)
-        .unwrap()
-        .unwrap();
+    bech32::encode_to_fmt_anycase(&mut encoded, hrp, &base32, Variant::Bech32).unwrap().unwrap();
     test(&*encoded == "bech321qqqsyrhqy2a");
 
     hprintln!("{}", encoded).unwrap();

Diff for: embedded/with-allocator/src/main.rs

@@ -3,18 +3,18 @@
 #![no_std]
 
 extern crate alloc;
-use panic_halt as _;
-
-use self::alloc::string::ToString;
-use self::alloc::vec;
-use self::alloc::vec::Vec;
 use core::alloc::Layout;
 
 use alloc_cortex_m::CortexMHeap;
-use bech32::{self, FromBase32, ToBase32, Variant, Hrp};
+use bech32::{self, FromBase32, Hrp, ToBase32, Variant};
 use cortex_m::asm;
 use cortex_m_rt::entry;
 use cortex_m_semihosting::{debug, hprintln};
+use panic_halt as _;
+
+use self::alloc::string::ToString;
+use self::alloc::vec;
+use self::alloc::vec::Vec;
 
 #[global_allocator]
 static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
@@ -27,12 +27,7 @@ fn main() -> ! {
     unsafe { ALLOCATOR.init(cortex_m_rt::heap_start() as usize, HEAP_SIZE) }
 
     let hrp = Hrp::parse("bech32").unwrap();
-    let encoded = bech32::encode(
-        hrp,
-        vec![0x00, 0x01, 0x02].to_base32(),
-        Variant::Bech32,
-    )
-    .unwrap();
+    let encoded = bech32::encode(hrp, vec![0x00, 0x01, 0x02].to_base32(), Variant::Bech32).unwrap();
     test(encoded == "bech321qqqsyrhqy2a".to_string());
 
     hprintln!("{}", encoded).unwrap();

Diff for: githooks/pre-commit

@@ -47,3 +47,6 @@ git diff-index --check --cached $against -- || exit 1
 
 # Check that code lints cleanly.
 cargo clippy --all-features -- -D warnings || exit 1
+
+# Check that there are no formatting issues.
+cargo +nightly fmt --check || exit 1

Diff for: src/error.rs

@@ -1,13 +1,5 @@
-// Written by the Rust Bitcoin developers.
 // SPDX-License-Identifier: CC0-1.0
 
-// TODO: We can get this from `bitcoin-internals` crate once that is released.
-
-//! # Error
-//!
-//! Error handling macros and helpers.
-//!
-
 /// Formats error.
 ///
 /// If `std` feature is OFF appends error source (delimited by `: `). We do this because

Diff for: src/lib.rs

@@ -11,24 +11,6 @@
 //!
 //! The original description in [BIP-0173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)
 //! has more details. See also [BIP-0350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki).
-//!
-#![cfg_attr(
-    feature = "std",
-    doc = "
-# Examples
-```
-use bech32::{self, FromBase32, ToBase32, Variant, Hrp};
-let hrp = Hrp::parse(\"bech32\").expect(\"bech32 is valid\");
-let encoded = bech32::encode(hrp, vec![0x00, 0x01, 0x02].to_base32(), Variant::Bech32).unwrap();
-assert_eq!(encoded, \"bech321qqqsyrhqy2a\".to_string());
-let (hrp, data, variant) = bech32::decode(&encoded).unwrap();
-assert_eq!(hrp.to_string(), \"bech32\");
-assert_eq!(Vec::<u8>::from_base32(&data).unwrap(), vec![0x00, 0x01, 0x02]);
-assert_eq!(variant, Variant::Bech32);
-```
-"
-)]
-//!
 
 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
 // Experimental features we need.
@@ -452,9 +434,8 @@ pub fn encode_to_fmt_anycase<T: AsRef<[u5]>>(
 ///
 /// This method is intended for implementing traits from [`std::fmt`].
 ///
-/// # Errors
+/// # Deviations from standard.
 ///
-/// * Deviations from standard.
 /// * No length limits are enforced for the data part.
 pub fn encode_without_checksum_to_fmt<T: AsRef<[u5]>>(
     fmt: &mut dyn fmt::Write,
@@ -502,9 +483,8 @@ impl Variant {
 
 /// Encodes a bech32 payload to string.
 ///
-/// # Errors
+/// # Deviations from standard.
 ///
-/// * Deviations from standard.
 /// * No length limits are enforced for the data part.
 #[cfg(feature = "alloc")]
 pub fn encode<T: AsRef<[u5]>>(hrp: Hrp, data: T, variant: Variant) -> Result<String, Error> {
@@ -515,9 +495,8 @@ pub fn encode<T: AsRef<[u5]>>(hrp: Hrp, data: T, variant: Variant) -> Result<Str
 
 /// Encodes a bech32 payload to string without the checksum.
 ///
-/// # Errors
+/// # Deviations from standard.
 ///
-/// * Deviations from standard.
 /// * No length limits are enforced for the data part.
 #[cfg(feature = "alloc")]
 pub fn encode_without_checksum<T: AsRef<[u5]>>(hrp: Hrp, data: T) -> Result<String, Error> {

Diff for: src/primitives/gf32.rs

@@ -16,6 +16,8 @@ use core::{fmt, num, ops};
 #[cfg(all(test, mutate))]
 use mutagen::mutate;
 
+use crate::write_err;
+
 /// Logarithm table of each bech32 element, as a power of alpha = Z.
 ///
 /// Includes Q as 0 but this is false; you need to exclude Q because it has no discrete log. If we
@@ -317,12 +319,27 @@ pub enum Error {
 }
 
 impl fmt::Display for Error {
-    fn fmt(&self, _f: &mut fmt::Formatter<'_>) -> fmt::Result { todo!() }
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        use Error::*;
+
+        match *self {
+            NotAByte(ref e) => write_err!(f, "invalid field element"; e),
+            InvalidByte(ref b) => write!(f, "invalid byte in field element: {:#04x}", b),
+            InvalidChar(ref c) => write!(f, "invalid char in field element: {}", c),
+        }
+    }
 }
 
 #[cfg(feature = "std")]
 impl std::error::Error for Error {
-    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { todo!() }
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        use Error::*;
+
+        match *self {
+            NotAByte(ref e) => Some(e),
+            InvalidByte(_) | InvalidChar(_) => None,
+        }
+    }
 }
 
 impl From<num::TryFromIntError> for Error {