Merge #166: Unify hyperlinks across documentation

99f6add Unify hyperlinks across documentation (bishopcheckmate)

Pull request description:

  Hey,
  I was browsing the master docs and found some hyperlinks broken due to missing `///` line separator.
  I also unified the way that hyperlinks are written, and some stuff like `fmt::Write` `std::io::Write` or removed the `crate::` prefixes

ACKs for top commit:
  apoelstra:
    ACK 99f6add thanks for doing this!

Tree-SHA512: e26fe0913349ab48b0c568aa2c7bc213b4c88d2aa0aa6471be6dc8ce9d5b1bb279959dfc385e63232f29649fbc80e34bdb360c69873485c22a5530d6f13b1719

Author: apoelstra

src/lib.rs

@@ -15,13 +15,11 @@
 //! - Non-segwit stuff and you have an allocator, use the top level API. For normal usage the
 //!   [`encode`] and [`decode`] functions should suffice. There are also various other functions for
 //!   explicit control of the checksum algorithm and the case used when encoding.
-//! - Non-segwit stuff and you do *not* have an allocator, use the
-//!   [`primitives::decode::CheckedHrpstring`] type for decoding. For encoding we provide various
-//!   top level functions of the form `encode*_to_fmt`.
-//! - To define your own checksum algorithm implement [`crate::Checksum`] (see example below).
+//! - Non-segwit stuff and you do *not* have an allocator, use the [`CheckedHrpstring`] type for
+//!   decoding. For encoding we provide various top level functions of the form `encode*_to_fmt`.
+//! - To define your own checksum algorithm implement [`Checksum`] (see example below).
 //!
-//! 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).
+//! The original description in [BIP-173] has more details. See also [BIP-350].
 //!
 //! # Deviation from spec
 //!
@@ -121,6 +119,9 @@
 //! # }
 //! ```
 //!
+//! [BIP-173]: <https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki>
+//! [BIP-350]: <https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki>
+//! [`CheckedHrpstring`]: crate::primitives::decode::CheckedHrpstring
 //! [`Checksum::CODE_LENGTH`]: crate::primitives::checksum::Checksum::CODE_LENGTH
 
 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
@@ -339,10 +340,12 @@ pub fn encode_upper_to_fmt<Ck: Checksum, W: fmt::Write>(
     Ok(())
 }
 
-/// Encodes `data` to a writer ([`std::io::Write`]) as a lowercase bech32 encoded string.
+/// Encodes `data` to a writer ([`io::Write`]) as a lowercase bech32 encoded string.
 ///
 /// Encoded string will be prefixed with the `hrp` and have a checksum appended as specified by the
 /// `Ck` algorithm (`NoChecksum` to exclude checksum all together).
+///
+/// [`io::Write`]: std::io::Write
 #[cfg(feature = "std")]
 #[inline]
 pub fn encode_to_writer<Ck: Checksum, W: std::io::Write>(
@@ -353,10 +356,12 @@ pub fn encode_to_writer<Ck: Checksum, W: std::io::Write>(
     encode_lower_to_writer::<Ck, W>(w, hrp, data)
 }
 
-/// Encodes `data` to a writer ([`std::io::Write`]) as a lowercase bech32 encoded string.
+/// Encodes `data` to a writer ([`io::Write`]) as a lowercase bech32 encoded string.
 ///
 /// Encoded string will be prefixed with the `hrp` and have a checksum appended as specified by the
 /// `Ck` algorithm (`NoChecksum` to exclude checksum all together).
+///
+/// [`io::Write`]: std::io::Write
 #[cfg(feature = "std")]
 #[inline]
 pub fn encode_lower_to_writer<Ck: Checksum, W: std::io::Write>(
@@ -386,10 +391,12 @@ pub fn encode_lower_to_writer<Ck: Checksum, W: std::io::Write>(
     Ok(())
 }
 
-/// Encodes `data` to a writer ([`std::io::Write`]) as a uppercase bech32 encoded string.
+/// Encodes `data` to a writer ([`io::Write`]) as a uppercase bech32 encoded string.
 ///
 /// Encoded string will be prefixed with the `hrp` and have a checksum appended as specified by the
 /// `Ck` algorithm (`NoChecksum` to exclude checksum all together).
+///
+/// [`io::Write`]: std::io::Write
 #[cfg(feature = "std")]
 #[inline]
 pub fn encode_upper_to_writer<Ck: Checksum, W: std::io::Write>(

src/primitives/checksum.rs

@@ -165,7 +165,9 @@ pub trait PackedFe32: Copy + PartialEq + Eq + ops::BitXor<Self, Output = Self> {
     fn mul_by_x_then_add(&mut self, degree: usize, add: u8) -> u8;
 }
 
-/// A placeholder type used as part of the [`crate::primitives::NoChecksum`] "checksum".
+/// A placeholder type used as part of the [`NoChecksum`] "checksum".
+///
+/// [`NoChecksum`]: crate::primitives::NoChecksum
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub struct PackedNull;
 

src/primitives/gf32.rs

@@ -2,13 +2,15 @@
 
 //! GF32 - Galois Field over 32 elements.
 //!
-//! Implements GF32 arithmetic, defined and encoded as in BIP-0173 "bech32".
+//! Implements GF32 arithmetic, defined and encoded as in [BIP-173] "bech32".
 //!
 //! > A finite field is a finite set which is a field; this means that multiplication, addition,
 //! > subtraction and division (excluding division by zero) are defined and satisfy the rules of
 //! > arithmetic known as the field axioms.
 //!
 //! ref: <https://en.wikipedia.org/wiki/Finite_field>
+//!
+//! [BIP-173]: <https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki>
 
 use core::convert::{Infallible, TryFrom};
 use core::{fmt, num, ops};

src/primitives/hrp.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-//! Provides an `Hrp` type that represents the human-readable part of a bech32 encoded string.
+//! Provides an [`Hrp`] type that represents the human-readable part of a bech32 encoded string.
 //!
 //! > The human-readable part, which is intended to convey the type of data, or anything else that
 //! > is relevant to the reader. This part MUST contain 1 to 83 US-ASCII characters, with each
@@ -195,7 +195,7 @@ impl Hrp {
     ///
     /// [BIP-173] states that the HRP must be either "bc" or "tb".
     ///
-    /// [BIP-173]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#user-content-Segwit_address_format
+    /// [BIP-173]: <https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#user-content-Segwit_address_format>
     #[inline]
     pub fn is_valid_segwit(&self) -> bool {
         self.is_valid_on_mainnet() || self.is_valid_on_testnet()
@@ -371,6 +371,7 @@ impl<'b> FusedIterator for LowercaseCharIter<'b> {}
 fn is_ascii_uppercase(b: u8) -> bool { (65..=90).contains(&b) }
 
 /// Errors encountered while checking the human-readable part as defined by [BIP-173].
+///
 /// [BIP-173]: <https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#user-content-Bech32>
 #[derive(Clone, Debug, PartialEq, Eq)]
 #[non_exhaustive]

src/primitives/mod.rs

@@ -17,11 +17,13 @@ use checksum::{Checksum, PackedNull};
 pub enum NoChecksum {}
 
 /// The bech32 checksum algorithm, defined in [BIP-173].
+///
 /// [BIP-173]: <https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki>
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Bech32 {}
 
 /// The bech32m checksum algorithm, defined in [BIP-350].
+///
 /// [BIP-350]: <https://github.com/bitcoin/bips/blob/master/bip-0359.mediawiki>
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum Bech32m {}

src/primitives/segwit.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-//! Segregated Witness functionality - useful for enforcing parts of [`BIP-173`] and [`BIP-350`].
+//! Segregated Witness functionality - useful for enforcing parts of [BIP-173] and [BIP-350].
 //!
 //! [BIP-173]: <https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki>
 //! [BIP-350]: <https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki>

src/segwit.rs

@@ -227,10 +227,12 @@ pub fn encode_upper_to_fmt_unchecked<W: fmt::Write>(
     Ok(())
 }
 
-/// Encodes a segwit address to a writer ([`std::io::Write`]) using lowercase characters.
+/// Encodes a segwit address to a writer ([`io::Write`]) using lowercase characters.
 ///
 /// There are no guarantees that the written string is a valid segwit address unless all the
 /// parameters are valid. See the body of `encode()` to see the validity checks required.
+///
+/// [`io::Write`]: std::io::Write
 #[cfg(feature = "std")]
 #[inline]
 pub fn encode_to_writer_unchecked<W: std::io::Write>(
@@ -242,10 +244,12 @@ pub fn encode_to_writer_unchecked<W: std::io::Write>(
     encode_lower_to_writer_unchecked(w, hrp, witness_version, witness_program)
 }
 
-/// Encodes a segwit address to a writer ([`std::io::Write`]) using lowercase characters.
+/// Encodes a segwit address to a writer ([`io::Write`]) using lowercase characters.
 ///
 /// There are no guarantees that the written string is a valid segwit address unless all the
 /// parameters are valid. See the body of `encode()` to see the validity checks required.
+///
+/// [`io::Write`]: std::io::Write
 #[cfg(feature = "std")]
 #[inline]
 pub fn encode_lower_to_writer_unchecked<W: std::io::Write>(
@@ -280,12 +284,14 @@ pub fn encode_lower_to_writer_unchecked<W: std::io::Write>(
     Ok(())
 }
 
-/// Encodes a segwit address to a [`std::io::Write`] writer using uppercase characters.
+/// Encodes a segwit address to a [`io::Write`] writer using uppercase characters.
 ///
 /// This is provided for use when creating QR codes.
 ///
 /// There are no guarantees that the written string is a valid segwit address unless all the
 /// parameters are valid. See the body of `encode()` to see the validity checks required.
+///
+/// [`io::Write`]: std::io::Write
 #[cfg(feature = "std")]
 #[inline]
 pub fn encode_upper_to_writer_unchecked<W: std::io::Write>(