Merge #134: Do some docs fixes

ea97465 Remove backticks for bip names (Tobin C. Harding)
8dec93d Drop docs usage of "higher" (Tobin C. Harding)
6280935 Update "crate level API" docs (Tobin C. Harding)
521d963 Fix incorrect HRP docs (Tobin C. Harding)
9f7c21a Fix links (Tobin C. Harding)
d432a4f Fix rendered module docs (Tobin C. Harding)

Pull request description:

  Do a bunch of rustdocs fixes.

ACKs for top commit:
  clarkmoody:
    ACK ea97465
  apoelstra:
    ACK ea97465

Tree-SHA512: 59505d57f5bfe12364e3fef1daaf5d45e6b4a317b1d64d2173283a5563326a919fdc5faa4d0de0b199339b00b528b1a358c43347b8bdd0effb303d5e186de222

src/hrp.rs

@@ -1,4 +1,8 @@
 // SPDX-License-Identifier: MIT
 
+//! Re-exports the hrp types from [`primitives::hrp`] to make importing ergonomic for the top level APIs.
+//!
+//! [`primitives::hrp`]: crate::primitives::hrp
+
 #[doc(inline)]
 pub use crate::primitives::hrp::{Hrp, BC, BCRT, TB};

src/lib.rs

@@ -141,11 +141,8 @@ extern crate alloc;
 extern crate core;
 
 mod error;
-/// Re-exports the hrp types from [`primitives::hrp`] to make importing ergonomic for the top level APIs.
 pub mod hrp;
-/// All the primitive types and functionality used in encoding and decoding.
 pub mod primitives;
-/// API for encoding and decoding segwit addresses.
 pub mod segwit;
 
 #[cfg(all(feature = "alloc", not(feature = "std"), not(test)))]

src/primitives/decode.rs

@@ -5,7 +5,7 @@
 //! You should only need to use this module directly if you want control over exactly what is
 //! checked and when it is checked (correct bech32 characters, valid checksum, valid checksum for
 //! specific checksum algorithm, etc). If you are parsing/validating modern (post BIP-350) bitcoin
-//! segwit addresses consider using the higher crate level API.
+//! segwit addresses consider using the [`crate::segwit`] API.
 //!
 //! If you do find yourself using this module directly then consider using the most general type
 //! that serves your purposes, each type can be created by parsing an address string to `new`. You

src/primitives/encode.rs

@@ -7,7 +7,7 @@
 //! prepending HRP strings etc.
 //!
 //! In general, directly using these adaptors is not very ergonomic, and users are recommended to
-//! instead use the higher-level functions at the root of this crate.
+//! instead use the crate level API.
 //!
 //! WARNING: This module does not enforce the maximum length of an encoded bech32 string (90 chars).
 //!

src/primitives/hrp.rs

@@ -191,7 +191,7 @@ impl Hrp {
     #[allow(clippy::len_without_is_empty)] // HRP is never empty.
     pub fn len(&self) -> usize { self.size }
 
-    /// Returns `true` if this [`Hrp`] is valid according to the bips.
+    /// Returns `true` if this HRP is valid according to the bips.
     ///
     /// [BIP-173] states that the HRP must be either "bc" or "tb".
     ///
@@ -201,19 +201,19 @@ impl Hrp {
         self.is_valid_on_mainnet() || self.is_valid_on_testnet()
     }
 
-    /// Returns `true` if this hrpstring is valid on the Bitcoin network i.e., HRP is "bc".
+    /// Returns `true` if this HRP is valid on the Bitcoin network i.e., HRP is "bc".
     #[inline]
     pub fn is_valid_on_mainnet(&self) -> bool { *self == self::BC }
 
-    /// Returns `true` if this hrpstring is valid on the Bitcoin testnet network i.e., HRP is "tb".
+    /// Returns `true` if this HRP is valid on the Bitcoin testnet network i.e., HRP is "tb".
     #[inline]
     pub fn is_valid_on_testnet(&self) -> bool { *self == self::TB }
 
-    /// Returns `true` if this hrpstring is valid on the Bitcoin signet network i.e., HRP is "tb".
+    /// Returns `true` if this HRP is valid on the Bitcoin signet network i.e., HRP is "tb".
     #[inline]
     pub fn is_valid_on_signet(&self) -> bool { *self == self::TB }
 
-    /// Returns `true` if this hrpstring is valid on the Bitcoin regtest network i.e., HRP is "bcrt".
+    /// Returns `true` if this HRP is valid on the Bitcoin regtest network i.e., HRP is "bcrt".
     #[inline]
     pub fn is_valid_on_regtest(&self) -> bool { *self == self::BCRT }
 }

src/primitives/mod.rs

@@ -24,7 +24,7 @@ pub enum Bech32 {}
 
 /// The bech32m checksum algorithm, defined in [BIP-350].
 ///
-/// [BIP-350]: <https://github.com/bitcoin/bips/blob/master/bip-0359.mediawiki>
+/// [BIP-350]: <https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki>
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Bech32m {}
 

src/segwit.rs

@@ -89,8 +89,8 @@ pub fn decode(s: &str) -> Result<(Hrp, Fe32, Vec<u8>), DecodeError> {
 /// Does validity checks on the `witness_version`, length checks on the `witness_program`, and
 /// checks the total encoded string length.
 ///
-/// As specified by [`BIP-350`] we use the [`Bech32m`] checksum algorithm for witness versions 1 and
-/// above, and for witness version 0 we use the original ([`BIP-173`]) [`Bech32`] checksum
+/// As specified by [BIP-350] we use the [`Bech32m`] checksum algorithm for witness versions 1 and
+/// above, and for witness version 0 we use the original ([BIP-173]) [`Bech32`] checksum
 /// algorithm.
 ///
 /// See also [`encode_v0`] or [`encode_v1`].