From 573f8ce724695092ed377fed9338528c4d9cf19b Mon Sep 17 00:00:00 2001
From: "Jamil Lambert, PhD" <Jamil.Lambert@proton.me>
Date: Wed, 3 Jul 2024 13:52:21 +0100
Subject: [PATCH 1/4] Add backticks to rustdoc links

Links in rustdocs should be formatted with a backtick.  This has been
changed throughout Units.
---
 units/src/amount.rs | 104 ++++++++++++++++++++++----------------------
 units/src/parse.rs  |   4 +-
 2 files changed, 54 insertions(+), 54 deletions(-)

diff --git a/units/src/amount.rs b/units/src/amount.rs
index 8b9b78ba5..705b19ff5 100644
--- a/units/src/amount.rs
+++ b/units/src/amount.rs
@@ -2,7 +2,7 @@
 
 //! Bitcoin amounts.
 //!
-//! This module mainly introduces the [Amount] and [SignedAmount] types.
+//! This module mainly introduces the [`Amount`] and [`SignedAmount`] types.
 //! We refer to the documentation on the types for more information.
 
 #[cfg(feature = "alloc")]
@@ -79,7 +79,7 @@ impl Denomination {
         }
     }
 
-    /// The different str forms of denominations that are recognized.
+    /// The different `str` forms of denominations that are recognized.
     fn forms(s: &str) -> Option<Self> {
         match s {
             "BTC" | "btc" => Some(Denomination::Bitcoin),
@@ -105,7 +105,7 @@ impl fmt::Display for Denomination {
 impl FromStr for Denomination {
     type Err = ParseDenominationError;
 
-    /// Convert from a str to Denomination.
+    /// Convert from a `str` to `Denomination`.
     ///
     /// # Accepted Denominations
     ///
@@ -513,7 +513,7 @@ fn is_too_precise(s: &str, precision: usize) -> Option<usize> {
 const INPUT_STRING_LEN_LIMIT: usize = 50;
 
 /// Parse decimal string in the given denomination into a satoshi value and a
-/// bool indicator for a negative amount.
+/// `bool` indicator for a negative amount.
 fn parse_signed_to_satoshi(
     mut s: &str,
     denom: Denomination,
@@ -832,16 +832,16 @@ fn fmt_satoshi_in(
 
 /// An amount.
 ///
-/// The [Amount] type can be used to express Bitcoin amounts that support
+/// The [`Amount`] type can be used to express Bitcoin amounts that support
 /// arithmetic and conversion to various denominations.
 ///
 ///
 /// Warning!
 ///
-/// This type implements several arithmetic operations from [core::ops].
+/// This type implements several arithmetic operations from [`core::ops`].
 /// To prevent errors due to overflow or underflow when using these operations,
 /// it is advised to instead use the checked arithmetic methods whose names
-/// start with `checked_`.  The operations from [core::ops] that [Amount]
+/// start with `checked_`.  The operations from [`core::ops`] that [`Amount`]
 /// implements will panic when overflow or underflow occurs.  Also note that
 /// since the internal representation of amounts is unsigned, subtracting below
 /// zero is considered an underflow and will cause a panic if you're not using
@@ -867,19 +867,19 @@ impl Amount {
     /// The number of bytes that an amount contributes to the size of a transaction.
     pub const SIZE: usize = 8; // Serialized length of a u64.
 
-    /// Create an [Amount] with satoshi precision and the given number of satoshis.
+    /// Create an [`Amount`] with satoshi precision and the given number of satoshis.
     pub const fn from_sat(satoshi: u64) -> Amount { Amount(satoshi) }
 
     /// Gets the number of satoshis in this [`Amount`].
     pub fn to_sat(self) -> u64 { self.0 }
 
-    /// Convert from a value expressing bitcoins to an [Amount].
+    /// Convert from a value expressing bitcoins to an [`Amount`].
     #[cfg(feature = "alloc")]
     pub fn from_btc(btc: f64) -> Result<Amount, ParseAmountError> {
         Amount::from_float_in(btc, Denomination::Bitcoin)
     }
 
-    /// Convert from a value expressing integer values of bitcoins to an [Amount]
+    /// Convert from a value expressing integer values of bitcoins to an [`Amount`]
     /// in const context.
     ///
     /// # Panics
@@ -903,7 +903,7 @@ impl Amount {
     /// Parse a decimal string as a value in the given denomination.
     ///
     /// Note: This only parses the value string.  If you want to parse a value
-    /// with denomination, use [FromStr].
+    /// with denomination, use [`FromStr`].
     pub fn from_str_in(s: &str, denom: Denomination) -> Result<Amount, ParseAmountError> {
         let (negative, satoshi) =
             parse_signed_to_satoshi(s, denom).map_err(|error| error.convert(false))?;
@@ -914,15 +914,15 @@ impl Amount {
     }
 
     /// Parses amounts with denomination suffix like they are produced with
-    /// [Self::to_string_with_denomination] or with [fmt::Display].
+    /// [`Self::to_string_with_denomination`] or with [`fmt::Display`].
     /// If you want to parse only the amount without the denomination,
-    /// use [Self::from_str_in].
+    /// use [`Self::from_str_in`].
     pub fn from_str_with_denomination(s: &str) -> Result<Amount, ParseError> {
         let (amt, denom) = split_amount_and_denomination(s)?;
         Amount::from_str_in(amt, denom).map_err(Into::into)
     }
 
-    /// Express this [Amount] as a floating-point value in the given denomination.
+    /// Express this [`Amount`] as a floating-point value in the given denomination.
     ///
     /// Please be aware of the risk of using floating-point numbers.
     #[cfg(feature = "alloc")]
@@ -944,7 +944,7 @@ impl Amount {
     #[cfg(feature = "alloc")]
     pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
 
-    /// Convert this [Amount] in floating-point notation with a given
+    /// Convert this [`Amount`] in floating-point notation with a given
     /// denomination.
     /// Can return error if the amount is too big, too precise or negative.
     ///
@@ -980,7 +980,7 @@ impl Amount {
         }
     }
 
-    /// Format the value of this [Amount] in the given denomination.
+    /// Format the value of this [`Amount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[rustfmt::skip]
@@ -989,13 +989,13 @@ impl Amount {
         fmt_satoshi_in(self.to_sat(), false, f, denom, false, FormatOptions::default())
     }
 
-    /// Get a string number of this [Amount] in the given denomination.
+    /// Get a string number of this [`Amount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() }
 
-    /// Get a formatted string of this [Amount] in the given denomination,
+    /// Get a formatted string of this [`Amount`] in the given denomination,
     /// suffixed with the abbreviation for the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_with_denomination(self, denom: Denomination) -> String {
@@ -1006,33 +1006,33 @@ impl Amount {
 
     /// Checked addition.
     ///
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_add(self, rhs: Amount) -> Option<Amount> {
         self.0.checked_add(rhs.0).map(Amount)
     }
 
     /// Checked subtraction.
     ///
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_sub(self, rhs: Amount) -> Option<Amount> {
         self.0.checked_sub(rhs.0).map(Amount)
     }
 
     /// Checked multiplication.
     ///
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_mul(self, rhs: u64) -> Option<Amount> { self.0.checked_mul(rhs).map(Amount) }
 
     /// Checked integer division.
     ///
     /// Be aware that integer division loses the remainder if no exact division
     /// can be made.
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_div(self, rhs: u64) -> Option<Amount> { self.0.checked_div(rhs).map(Amount) }
 
     /// Checked remainder.
     ///
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_rem(self, rhs: u64) -> Option<Amount> { self.0.checked_rem(rhs).map(Amount) }
 
     /// Unchecked addition.
@@ -1217,16 +1217,16 @@ enum DisplayStyle {
 
 /// A signed amount.
 ///
-/// The [SignedAmount] type can be used to express Bitcoin amounts that support
+/// The [`SignedAmount`] type can be used to express Bitcoin amounts that support
 /// arithmetic and conversion to various denominations.
 ///
 ///
 /// Warning!
 ///
-/// This type implements several arithmetic operations from [core::ops].
+/// This type implements several arithmetic operations from [`core::ops`].
 /// To prevent errors due to overflow or underflow when using these operations,
 /// it is advised to instead use the checked arithmetic methods whose names
-/// start with `checked_`.  The operations from [core::ops] that [Amount]
+/// start with `checked_`.  The operations from [`core::ops`] that [`Amount`]
 /// implements will panic when overflow or underflow occurs.
 ///
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
@@ -1246,13 +1246,13 @@ impl SignedAmount {
     /// The maximum value of an amount.
     pub const MAX: SignedAmount = SignedAmount(i64::MAX);
 
-    /// Create an [SignedAmount] with satoshi precision and the given number of satoshis.
+    /// Create an [`SignedAmount`] with satoshi precision and the given number of satoshis.
     pub const fn from_sat(satoshi: i64) -> SignedAmount { SignedAmount(satoshi) }
 
     /// Gets the number of satoshis in this [`SignedAmount`].
     pub fn to_sat(self) -> i64 { self.0 }
 
-    /// Convert from a value expressing bitcoins to an [SignedAmount].
+    /// Convert from a value expressing bitcoins to an [`SignedAmount`].
     #[cfg(feature = "alloc")]
     pub fn from_btc(btc: f64) -> Result<SignedAmount, ParseAmountError> {
         SignedAmount::from_float_in(btc, Denomination::Bitcoin)
@@ -1261,7 +1261,7 @@ impl SignedAmount {
     /// Parse a decimal string as a value in the given denomination.
     ///
     /// Note: This only parses the value string.  If you want to parse a value
-    /// with denomination, use [FromStr].
+    /// with denomination, use [`FromStr`].
     pub fn from_str_in(s: &str, denom: Denomination) -> Result<SignedAmount, ParseAmountError> {
         match parse_signed_to_satoshi(s, denom).map_err(|error| error.convert(true))? {
             // (negative, amount)
@@ -1276,15 +1276,15 @@ impl SignedAmount {
     }
 
     /// Parses amounts with denomination suffix like they are produced with
-    /// [Self::to_string_with_denomination] or with [fmt::Display].
+    /// [`Self::to_string_with_denomination`] or with [`fmt::Display`].
     /// If you want to parse only the amount without the denomination,
-    /// use [Self::from_str_in].
+    /// use [`Self::from_str_in`].
     pub fn from_str_with_denomination(s: &str) -> Result<SignedAmount, ParseError> {
         let (amt, denom) = split_amount_and_denomination(s)?;
         SignedAmount::from_str_in(amt, denom).map_err(Into::into)
     }
 
-    /// Express this [SignedAmount] as a floating-point value in the given denomination.
+    /// Express this [`SignedAmount`] as a floating-point value in the given denomination.
     ///
     /// Please be aware of the risk of using floating-point numbers.
     #[cfg(feature = "alloc")]
@@ -1300,7 +1300,7 @@ impl SignedAmount {
     #[cfg(feature = "alloc")]
     pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
 
-    /// Convert this [SignedAmount] in floating-point notation with a given
+    /// Convert this [`SignedAmount`] in floating-point notation with a given
     /// denomination.
     /// Can return error if the amount is too big, too precise or negative.
     ///
@@ -1336,7 +1336,7 @@ impl SignedAmount {
         }
     }
 
-    /// Format the value of this [SignedAmount] in the given denomination.
+    /// Format the value of this [`SignedAmount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[rustfmt::skip]
@@ -1345,13 +1345,13 @@ impl SignedAmount {
         fmt_satoshi_in(self.unsigned_abs().to_sat(), self.is_negative(), f, denom, false, FormatOptions::default())
     }
 
-    /// Get a string number of this [SignedAmount] in the given denomination.
+    /// Get a string number of this [`SignedAmount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() }
 
-    /// Get a formatted string of this [SignedAmount] in the given denomination,
+    /// Get a formatted string of this [`SignedAmount`] in the given denomination,
     /// suffixed with the abbreviation for the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_with_denomination(self, denom: Denomination) -> String {
@@ -1360,45 +1360,45 @@ impl SignedAmount {
 
     // Some arithmetic that doesn't fit in `core::ops` traits.
 
-    /// Get the absolute value of this [SignedAmount].
+    /// Get the absolute value of this [`SignedAmount`].
     pub fn abs(self) -> SignedAmount { SignedAmount(self.0.abs()) }
 
-    /// Get the absolute value of this [SignedAmount] returning `Amount`.
+    /// Get the absolute value of this [`SignedAmount`] returning `Amount`.
     pub fn unsigned_abs(self) -> Amount { Amount(self.0.unsigned_abs()) }
 
-    /// Returns a number representing sign of this [SignedAmount].
+    /// Returns a number representing sign of this [`SignedAmount`].
     ///
     /// - `0` if the amount is zero
     /// - `1` if the amount is positive
     /// - `-1` if the amount is negative
     pub fn signum(self) -> i64 { self.0.signum() }
 
-    /// Returns `true` if this [SignedAmount] is positive and `false` if
-    /// this [SignedAmount] is zero or negative.
+    /// Returns `true` if this [`SignedAmount`] is positive and `false` if
+    /// this [`SignedAmount`] is zero or negative.
     pub fn is_positive(self) -> bool { self.0.is_positive() }
 
-    /// Returns `true` if this [SignedAmount] is negative and `false` if
-    /// this [SignedAmount] is zero or positive.
+    /// Returns `true` if this [`SignedAmount`] is negative and `false` if
+    /// this [`SignedAmount`] is zero or positive.
     pub fn is_negative(self) -> bool { self.0.is_negative() }
 
-    /// Get the absolute value of this [SignedAmount].
-    /// Returns [None] if overflow occurred. (`self == MIN`)
+    /// Get the absolute value of this [`SignedAmount`].
+    /// Returns [`None`] if overflow occurred. (`self == MIN`)
     pub fn checked_abs(self) -> Option<SignedAmount> { self.0.checked_abs().map(SignedAmount) }
 
     /// Checked addition.
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_add(self, rhs: SignedAmount) -> Option<SignedAmount> {
         self.0.checked_add(rhs.0).map(SignedAmount)
     }
 
     /// Checked subtraction.
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
         self.0.checked_sub(rhs.0).map(SignedAmount)
     }
 
     /// Checked multiplication.
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_mul(self, rhs: i64) -> Option<SignedAmount> {
         self.0.checked_mul(rhs).map(SignedAmount)
     }
@@ -1406,13 +1406,13 @@ impl SignedAmount {
     /// Checked integer division.
     /// Be aware that integer division loses the remainder if no exact division
     /// can be made.
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_div(self, rhs: i64) -> Option<SignedAmount> {
         self.0.checked_div(rhs).map(SignedAmount)
     }
 
     /// Checked remainder.
-    /// Returns [None] if overflow occurred.
+    /// Returns [`None`] if overflow occurred.
     pub fn checked_rem(self, rhs: i64) -> Option<SignedAmount> {
         self.0.checked_rem(rhs).map(SignedAmount)
     }
@@ -1435,8 +1435,8 @@ impl SignedAmount {
     /// On overflow, panics in debug mode, wraps in release mode.
     pub fn unchecked_sub(self, rhs: SignedAmount) -> SignedAmount { Self(self.0 - rhs.0) }
 
-    /// Subtraction that doesn't allow negative [SignedAmount]s.
-    /// Returns [None] if either [self], `rhs` or the result is strictly negative.
+    /// Subtraction that doesn't allow negative [`SignedAmount`]s.
+    /// Returns [`None`] if either [`self`], `rhs` or the result is strictly negative.
     pub fn positive_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
         if self.is_negative() || rhs.is_negative() || rhs > self {
             None
diff --git a/units/src/parse.rs b/units/src/parse.rs
index 46b411f29..bdce64262 100644
--- a/units/src/parse.rs
+++ b/units/src/parse.rs
@@ -377,7 +377,7 @@ impl From<ParseIntError> for UnprefixedHexError {
     fn from(e: ParseIntError) -> Self { Self::ParseInt(e) }
 }
 
-/// Error when hex string is missing a prefix (e.g. 0x).
+/// Error when hex string is missing a prefix (e.g. `0x`).
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct MissingPrefixError {
     hex: String,
@@ -397,7 +397,7 @@ impl fmt::Display for MissingPrefixError {
 #[cfg(feature = "std")]
 impl std::error::Error for MissingPrefixError {}
 
-/// Error when hex string contains a prefix (e.g. 0x).
+/// Error when hex string contains a prefix (e.g. `0x`).
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct ContainsPrefixError {
     hex: String,

From 75f317a689501a79eea6b04efcda28fa12ccfe46 Mon Sep 17 00:00:00 2001
From: "Jamil Lambert, PhD" <Jamil.Lambert@proton.me>
Date: Wed, 3 Jul 2024 15:09:02 +0100
Subject: [PATCH 2/4] Fix rustdoc grammar

In the rustdocs, made all function descriptions third person. Corrected
some grammar and improved some wording.
---
 units/src/amount.rs            | 62 +++++++++++++++++++++-------------
 units/src/block.rs             |  2 +-
 units/src/fee_rate.rs          | 10 +++---
 units/src/locktime/absolute.rs |  6 ++--
 units/src/locktime/relative.rs | 10 +++---
 units/src/parse.rs             | 45 ++++++++++++------------
 units/src/weight.rs            |  4 +--
 7 files changed, 76 insertions(+), 63 deletions(-)

diff --git a/units/src/amount.rs b/units/src/amount.rs
index 705b19ff5..9290d9e22 100644
--- a/units/src/amount.rs
+++ b/units/src/amount.rs
@@ -67,7 +67,7 @@ impl Denomination {
         }
     }
 
-    /// Returns stringly representation of this
+    /// Returns a string representation of this denomination.
     fn as_str(self) -> &'static str {
         match self {
             Denomination::Bitcoin => "BTC",
@@ -105,7 +105,7 @@ impl fmt::Display for Denomination {
 impl FromStr for Denomination {
     type Err = ParseDenominationError;
 
-    /// Convert from a `str` to `Denomination`.
+    /// Converts from a `str` to a `Denomination`.
     ///
     /// # Accepted Denominations
     ///
@@ -260,7 +260,7 @@ impl std::error::Error for ParseAmountError {
     }
 }
 
-/// Returned when a parsed amount is too big or too small.
+/// Error returned when a parsed amount is too big or too small.
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 pub struct OutOfRangeError {
     is_signed: bool,
@@ -395,7 +395,7 @@ enum MissingDigitsKind {
     OnlyMinusSign,
 }
 
-/// Returned when the input contains an invalid character.
+/// Error returned when the input contains an invalid character.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct InvalidCharacterError {
     invalid_char: char,
@@ -458,7 +458,7 @@ impl std::error::Error for ParseDenominationError {
 #[non_exhaustive]
 pub struct MissingDenominationError;
 
-/// Parsing error, unknown denomination.
+/// Error returned when parsing an unknown denomination.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub struct UnknownDenominationError(InputString);
@@ -474,7 +474,7 @@ impl std::error::Error for UnknownDenominationError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { None }
 }
 
-/// Parsing error, possibly confusing denomination.
+/// Error returned when parsing a possibly confusing denomination.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub struct PossiblyConfusingDenominationError(InputString);
@@ -512,7 +512,7 @@ fn is_too_precise(s: &str, precision: usize) -> Option<usize> {
 
 const INPUT_STRING_LEN_LIMIT: usize = 50;
 
-/// Parse decimal string in the given denomination into a satoshi value and a
+/// Parses a decimal string in the given denomination into a satoshi value and a
 /// `bool` indicator for a negative amount.
 fn parse_signed_to_satoshi(
     mut s: &str,
@@ -867,19 +867,19 @@ impl Amount {
     /// The number of bytes that an amount contributes to the size of a transaction.
     pub const SIZE: usize = 8; // Serialized length of a u64.
 
-    /// Create an [`Amount`] with satoshi precision and the given number of satoshis.
+    /// Creates an [`Amount`] with satoshi precision and the given number of satoshis.
     pub const fn from_sat(satoshi: u64) -> Amount { Amount(satoshi) }
 
     /// Gets the number of satoshis in this [`Amount`].
     pub fn to_sat(self) -> u64 { self.0 }
 
-    /// Convert from a value expressing bitcoins to an [`Amount`].
+    /// Converts from a value expressing bitcoins to an [`Amount`].
     #[cfg(feature = "alloc")]
     pub fn from_btc(btc: f64) -> Result<Amount, ParseAmountError> {
         Amount::from_float_in(btc, Denomination::Bitcoin)
     }
 
-    /// Convert from a value expressing integer values of bitcoins to an [`Amount`]
+    /// Converts from a value expressing integer values of bitcoins to an [`Amount`]
     /// in const context.
     ///
     /// # Panics
@@ -900,7 +900,7 @@ impl Amount {
         }
     }
 
-    /// Parse a decimal string as a value in the given denomination.
+    /// Parses a decimal string as a value in the given denomination.
     ///
     /// Note: This only parses the value string.  If you want to parse a value
     /// with denomination, use [`FromStr`].
@@ -922,7 +922,7 @@ impl Amount {
         Amount::from_str_in(amt, denom).map_err(Into::into)
     }
 
-    /// Express this [`Amount`] as a floating-point value in the given denomination.
+    /// Expresses this [`Amount`] as a floating-point value in the given denomination.
     ///
     /// Please be aware of the risk of using floating-point numbers.
     #[cfg(feature = "alloc")]
@@ -930,7 +930,7 @@ impl Amount {
         f64::from_str(&self.to_string_in(denom)).unwrap()
     }
 
-    /// Express this [`Amount`] as a floating-point value in Bitcoin.
+    /// Expresses this [`Amount`] as a floating-point value in Bitcoin.
     ///
     /// Please be aware of the risk of using floating-point numbers.
     ///
@@ -944,7 +944,7 @@ impl Amount {
     #[cfg(feature = "alloc")]
     pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
 
-    /// Convert this [`Amount`] in floating-point notation with a given
+    /// Converts this [`Amount`] in floating-point notation with a given
     /// denomination.
     /// Can return error if the amount is too big, too precise or negative.
     ///
@@ -959,7 +959,7 @@ impl Amount {
         Amount::from_str_in(&value.to_string(), denom)
     }
 
-    /// Create an object that implements [`fmt::Display`] using specified denomination.
+    /// Creates an object that implements [`fmt::Display`] using specified denomination.
     pub fn display_in(self, denomination: Denomination) -> Display {
         Display {
             sats_abs: self.to_sat(),
@@ -968,7 +968,7 @@ impl Amount {
         }
     }
 
-    /// Create an object that implements [`fmt::Display`] dynamically selecting denomination.
+    /// Creates an object that implements [`fmt::Display`] dynamically selecting denomination.
     ///
     /// This will use BTC for values greater than or equal to 1 BTC and satoshis otherwise. To
     /// avoid confusion the denomination is always shown.
@@ -980,7 +980,7 @@ impl Amount {
         }
     }
 
-    /// Format the value of this [`Amount`] in the given denomination.
+    /// Formats the value of this [`Amount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[rustfmt::skip]
@@ -989,13 +989,13 @@ impl Amount {
         fmt_satoshi_in(self.to_sat(), false, f, denom, false, FormatOptions::default())
     }
 
-    /// Get a string number of this [`Amount`] in the given denomination.
+    /// Returns a formatted string of this [`Amount`] in the given denomination.
     ///
     /// Does not include the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() }
 
-    /// Get a formatted string of this [`Amount`] in the given denomination,
+    /// Returns a formatted string of this [`Amount`] in the given denomination,
     /// suffixed with the abbreviation for the denomination.
     #[cfg(feature = "alloc")]
     pub fn to_string_with_denomination(self, denom: Denomination) -> String {
@@ -1053,7 +1053,7 @@ impl Amount {
     /// On overflow, panics in debug mode, wraps in release mode.
     pub fn unchecked_sub(self, rhs: Amount) -> Amount { Self(self.0 - rhs.0) }
 
-    /// Convert to a signed amount.
+    /// Converts to a signed amount.
     pub fn to_signed(self) -> Result<SignedAmount, OutOfRangeError> {
         if self.to_sat() > SignedAmount::MAX.to_sat() as u64 {
             Err(OutOfRangeError::too_big(true))
@@ -1373,45 +1373,58 @@ impl SignedAmount {
     /// - `-1` if the amount is negative
     pub fn signum(self) -> i64 { self.0.signum() }
 
+    /// Checks if this [`SignedAmount`] is positive.
+    ///
     /// Returns `true` if this [`SignedAmount`] is positive and `false` if
     /// this [`SignedAmount`] is zero or negative.
     pub fn is_positive(self) -> bool { self.0.is_positive() }
 
+    /// Checks if this [`SignedAmount`] is negative.
+    ///
     /// Returns `true` if this [`SignedAmount`] is negative and `false` if
     /// this [`SignedAmount`] is zero or positive.
     pub fn is_negative(self) -> bool { self.0.is_negative() }
 
-    /// Get the absolute value of this [`SignedAmount`].
+    /// Returns the absolute value of this [`SignedAmount`].
+    ///
+    /// Consider using `unsigned_abs` which is often more practical.
+    ///
     /// Returns [`None`] if overflow occurred. (`self == MIN`)
     pub fn checked_abs(self) -> Option<SignedAmount> { self.0.checked_abs().map(SignedAmount) }
 
     /// Checked addition.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_add(self, rhs: SignedAmount) -> Option<SignedAmount> {
         self.0.checked_add(rhs.0).map(SignedAmount)
     }
 
     /// Checked subtraction.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
         self.0.checked_sub(rhs.0).map(SignedAmount)
     }
 
     /// Checked multiplication.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_mul(self, rhs: i64) -> Option<SignedAmount> {
         self.0.checked_mul(rhs).map(SignedAmount)
     }
 
     /// Checked integer division.
+    ///
     /// Be aware that integer division loses the remainder if no exact division
     /// can be made.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_div(self, rhs: i64) -> Option<SignedAmount> {
         self.0.checked_div(rhs).map(SignedAmount)
     }
 
     /// Checked remainder.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_rem(self, rhs: i64) -> Option<SignedAmount> {
         self.0.checked_rem(rhs).map(SignedAmount)
@@ -1436,6 +1449,7 @@ impl SignedAmount {
     pub fn unchecked_sub(self, rhs: SignedAmount) -> SignedAmount { Self(self.0 - rhs.0) }
 
     /// Subtraction that doesn't allow negative [`SignedAmount`]s.
+    ///
     /// Returns [`None`] if either [`self`], `rhs` or the result is strictly negative.
     pub fn positive_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
         if self.is_negative() || rhs.is_negative() || rhs > self {
@@ -1445,7 +1459,7 @@ impl SignedAmount {
         }
     }
 
-    /// Convert to an unsigned amount.
+    /// Converts to an unsigned amount.
     pub fn to_unsigned(self) -> Result<Amount, OutOfRangeError> {
         if self.is_negative() {
             Err(OutOfRangeError::negative())
@@ -1558,9 +1572,9 @@ impl core::iter::Sum for SignedAmount {
     }
 }
 
-/// Calculate the sum over the iterator using checked arithmetic.
+/// Calculates the sum over the iterator using checked arithmetic.
 pub trait CheckedSum<R>: private::SumSeal<R> {
-    /// Calculate the sum over the iterator using checked arithmetic. If an over or underflow would
+    /// Calculates the sum over the iterator using checked arithmetic. If an over or underflow would
     /// happen it returns `None`.
     fn checked_sum(self) -> Option<R>;
 }
diff --git a/units/src/block.rs b/units/src/block.rs
index bd3989f68..b79023135 100644
--- a/units/src/block.rs
+++ b/units/src/block.rs
@@ -155,7 +155,7 @@ impl TryFrom<BlockInterval> for relative::Height {
     }
 }
 
-/// The block interval is too big to be used as a relative lock time.
+/// Error returned when the block interval is too big to be used as a relative lock time.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct TooBigForRelativeBlockHeightError(u32);
 
diff --git a/units/src/fee_rate.rs b/units/src/fee_rate.rs
index 9dcb88ddb..648f34707 100644
--- a/units/src/fee_rate.rs
+++ b/units/src/fee_rate.rs
@@ -91,14 +91,14 @@ impl FeeRate {
         Some(Amount::from_sat(sats))
     }
 
-    /// Calculates fee by multiplying this fee rate by weight, in weight units, returning `None`
-    /// if overflow occurred.
+    /// Calculates the fee by multiplying this fee rate by weight, in weight units, returning `None`
+    /// if an overflow occurred.
     ///
     /// This is equivalent to `Self::checked_mul_by_weight()`.
     pub fn fee_wu(self, weight: Weight) -> Option<Amount> { self.checked_mul_by_weight(weight) }
 
-    /// Calculates fee by multiplying this fee rate by weight, in virtual bytes, returning `None`
-    /// if overflow occurred.
+    /// Calculates the fee by multiplying this fee rate by weight, in virtual bytes, returning `None`
+    /// if an overflow occurred.
     ///
     /// This is equivalent to converting `vb` to `weight` using `Weight::from_vb` and then calling
     /// `Self::fee_wu(weight)`.
@@ -122,7 +122,7 @@ impl From<FeeRate> for u64 {
     fn from(value: FeeRate) -> Self { value.to_sat_per_kwu() }
 }
 
-/// Computes ceiling so that fee computation is conservative.
+/// Computes the ceiling so that the fee computation is conservative.
 impl Mul<FeeRate> for Weight {
     type Output = Amount;
 
diff --git a/units/src/locktime/absolute.rs b/units/src/locktime/absolute.rs
index 64a5094ce..8eb2f95f5 100644
--- a/units/src/locktime/absolute.rs
+++ b/units/src/locktime/absolute.rs
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! Provides type `Height` and `Time` types used by the `rust-bitcoin` `absolute::LockTime` type.
+//! Provides `Height` and `Time` types used by the `rust-bitcoin` `absolute::LockTime` type.
 
 use core::fmt;
 
@@ -41,7 +41,7 @@ impl Height {
 
     /// Creates a `Height` from a hex string.
     ///
-    /// The input string is may or may not contain a typical hex prefix e.g., `0x`.
+    /// The input string may or may not contain a typical hex prefix e.g., `0x`.
     pub fn from_hex(s: &str) -> Result<Self, ParseHeightError> {
         parse_hex(s, Self::from_consensus)
     }
@@ -139,7 +139,7 @@ impl Time {
 
     /// Creates a `Time` from a hex string.
     ///
-    /// The input string is may or may not contain a typical hex prefix e.g., `0x`.
+    /// The input string may or may not contain a typical hex prefix e.g., `0x`.
     pub fn from_hex(s: &str) -> Result<Self, ParseTimeError> { parse_hex(s, Self::from_consensus) }
 
     /// Constructs a new block time.
diff --git a/units/src/locktime/relative.rs b/units/src/locktime/relative.rs
index b756def2d..fae92901e 100644
--- a/units/src/locktime/relative.rs
+++ b/units/src/locktime/relative.rs
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! Provides type `Height` and `Time` types used by the `rust-bitcoin` `relative::LockTime` type.
+//! Provides `Height` and `Time` types used by the `rust-bitcoin` `relative::LockTime` type.
 
 use core::fmt;
 
@@ -64,13 +64,13 @@ impl Time {
     /// The maximum relative block time (33,554,432 seconds or approx 388 days).
     pub const MAX: Self = Time(u16::MAX);
 
-    /// Create a [`Time`] using time intervals where each interval is equivalent to 512 seconds.
+    /// Creates a [`Time`] using time intervals where each interval is equivalent to 512 seconds.
     ///
     /// Encoding finer granularity of time for relative lock-times is not supported in Bitcoin.
     #[inline]
     pub const fn from_512_second_intervals(intervals: u16) -> Self { Time(intervals) }
 
-    /// Create a [`Time`] from seconds, converting the seconds into 512 second interval with
+    /// Creates a [`Time`] from seconds, converting the seconds into 512 second interval with
     /// truncating division.
     ///
     /// # Errors
@@ -87,8 +87,8 @@ impl Time {
         }
     }
 
-    /// Create a [`Time`] from seconds, converting the seconds into 512 second interval with ceiling
-    /// division.
+    /// Creates a [`Time`] from seconds, converting the seconds into 512 second intervals with
+    /// ceiling division.
     ///
     /// # Errors
     ///
diff --git a/units/src/parse.rs b/units/src/parse.rs
index bdce64262..1ba8fbb3a 100644
--- a/units/src/parse.rs
+++ b/units/src/parse.rs
@@ -160,11 +160,11 @@ macro_rules! impl_parse_str {
     }
 }
 
-/// Removes the prefix `0x` (or `0X`) from hex string.
+/// Removes the prefix `0x` (or `0X`) from a hex string.
 ///
 /// # Errors
 ///
-/// If input string does not contain a prefix.
+/// If the input string does not contain a prefix.
 pub fn hex_remove_prefix(s: &str) -> Result<&str, PrefixedHexError> {
     if let Some(checked) = s.strip_prefix("0x") {
         Ok(checked)
@@ -175,11 +175,11 @@ pub fn hex_remove_prefix(s: &str) -> Result<&str, PrefixedHexError> {
     }
 }
 
-/// Checks hex string does not have a prefix `0x` (or `0X`).
+/// Checks a hex string does not have a prefix `0x` (or `0X`).
 ///
 /// # Errors
 ///
-/// If input string contains a prefix.
+/// If the input string contains a prefix.
 pub fn hex_check_unprefixed(s: &str) -> Result<&str, UnprefixedHexError> {
     if s.starts_with("0x") || s.starts_with("0X") {
         return Err(ContainsPrefixError::new(s.into()).into());
@@ -203,8 +203,8 @@ pub fn hex_u32(s: &str) -> Result<u32, ParseIntError> {
 ///
 /// # Errors
 ///
-/// - If input string does not contain a `0x` (or `0X`) prefix.
-/// - If input string is not a valid hex encoding of a `u32`.
+/// - If the input string does not contain a `0x` (or `0X`) prefix.
+/// - If the input string is not a valid hex encoding of a `u32`.
 pub fn hex_u32_prefixed(s: &str) -> Result<u32, PrefixedHexError> {
     let checked = hex_remove_prefix(s)?;
     Ok(hex_u32_unchecked(checked)?)
@@ -214,19 +214,19 @@ pub fn hex_u32_prefixed(s: &str) -> Result<u32, PrefixedHexError> {
 ///
 /// # Errors
 ///
-/// - If input string contains a `0x` (or `0X`) prefix.
-/// - If input string is not a valid hex encoding of a `u32`.
+/// - If the input string contains a `0x` (or `0X`) prefix.
+/// - If the input string is not a valid hex encoding of a `u32`.
 pub fn hex_u32_unprefixed(s: &str) -> Result<u32, UnprefixedHexError> {
     let checked = hex_check_unprefixed(s)?;
     Ok(hex_u32_unchecked(checked)?)
 }
 
-/// Parses a `u32` from a hex string.
+/// Parses a `u32` from an unprefixed hex string without first checking for a prefix.
 ///
 /// # Errors
 ///
-/// - If input string is not a valid hex encoding of a `u32`.
-/// - With `InvalidDigit` due to the `x` if there is a prefix.
+/// - If the input string contains a `0x` (or `0X`) prefix, returns `InvalidDigit` due to the `x`.
+/// - If the input string is not a valid hex encoding of a `u32`.
 pub fn hex_u32_unchecked(s: &str) -> Result<u32, ParseIntError> {
     u32::from_str_radix(s, 16).map_err(|error| ParseIntError {
         input: s.into(),
@@ -252,8 +252,8 @@ pub fn hex_u128(s: &str) -> Result<u128, ParseIntError> {
 ///
 /// # Errors
 ///
-/// - If input string does not contain a `0x` (or `0X`) prefix.
-/// - If input string is not a valid hex encoding of a `u128`.
+/// - If the input string does not contain a `0x` (or `0X`) prefix.
+/// - If the input string is not a valid hex encoding of a `u128`.
 pub fn hex_u128_prefixed(s: &str) -> Result<u128, PrefixedHexError> {
     let checked = hex_remove_prefix(s)?;
     Ok(hex_u128_unchecked(checked)?)
@@ -263,19 +263,19 @@ pub fn hex_u128_prefixed(s: &str) -> Result<u128, PrefixedHexError> {
 ///
 /// # Errors
 ///
-/// - If input string contains a `0x` (or `0X`) prefix.
-/// - If input string is not a valid hex encoding of a `u128`.
+/// - If the input string contains a `0x` (or `0X`) prefix.
+/// - If the input string is not a valid hex encoding of a `u128`.
 pub fn hex_u128_unprefixed(s: &str) -> Result<u128, UnprefixedHexError> {
     let checked = hex_check_unprefixed(s)?;
     Ok(hex_u128_unchecked(checked)?)
 }
 
-/// Parses a `u128` from a hex string.
+/// Parses a `u128` from an unprefixed hex string without first checking for a prefix.
 ///
 /// # Errors
 ///
-/// - If input string is not a valid hex encoding of a `u128`.
-/// - With `InvalidDigit` due to the `x` if there is a prefix.
+/// - If the input string contains a `0x` (or `0X`) prefix, returns `InvalidDigit` due to the `x`.
+/// - If the input string is not a valid hex encoding of a `u128`.
 pub fn hex_u128_unchecked(s: &str) -> Result<u128, ParseIntError> {
     u128::from_str_radix(s, 16).map_err(|error| ParseIntError {
         input: s.into(),
@@ -296,8 +296,7 @@ pub(crate) fn hex_remove_optional_prefix(s: &str) -> &str {
     }
 }
 
-/// Error returned when parsing integer from an supposedly prefixed hex string for
-/// a type that can be created infallibly from an integer.
+/// Error returned when parsing an integer from a hex string that is supposed to contain a prefix.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum PrefixedHexError {
     /// Hex string is missing prefix.
@@ -337,7 +336,7 @@ impl From<ParseIntError> for PrefixedHexError {
     fn from(e: ParseIntError) -> Self { Self::ParseInt(e) }
 }
 
-/// Error returned when parsing integer from an supposedly un-prefixed hex string.
+/// Error returned when parsing an integer from a hex string that is not supposed to contain a prefix.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum UnprefixedHexError {
     /// Hex string contains prefix.
@@ -377,7 +376,7 @@ impl From<ParseIntError> for UnprefixedHexError {
     fn from(e: ParseIntError) -> Self { Self::ParseInt(e) }
 }
 
-/// Error when hex string is missing a prefix (e.g. `0x`).
+/// Error returned when a hex string is missing a prefix (e.g. `0x`).
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct MissingPrefixError {
     hex: String,
@@ -397,7 +396,7 @@ impl fmt::Display for MissingPrefixError {
 #[cfg(feature = "std")]
 impl std::error::Error for MissingPrefixError {}
 
-/// Error when hex string contains a prefix (e.g. `0x`).
+/// Error when hex string contains a prefix (e.g. 0x).
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct ContainsPrefixError {
     hex: String,
diff --git a/units/src/weight.rs b/units/src/weight.rs
index 3153bf4d7..1740c36c2 100644
--- a/units/src/weight.rs
+++ b/units/src/weight.rs
@@ -52,12 +52,12 @@ impl Weight {
     /// Constructs `Weight` from kilo weight units returning `None` if an overflow occurred.
     pub fn from_kwu(wu: u64) -> Option<Self> { wu.checked_mul(1000).map(Weight) }
 
-    /// Constructs `Weight` from virtual bytes, returning `None` on overflow.
+    /// Constructs `Weight` from virtual bytes, returning `None` if an overflow occurred.
     pub fn from_vb(vb: u64) -> Option<Self> {
         vb.checked_mul(Self::WITNESS_SCALE_FACTOR).map(Weight::from_wu)
     }
 
-    /// Constructs `Weight` from virtual bytes panicking on overflow.
+    /// Constructs `Weight` from virtual bytes panicking if an overflow occurred.
     ///
     /// # Panics
     ///

From 47e367f01124e4e445d1f62a367ac6d77a01c19e Mon Sep 17 00:00:00 2001
From: "Jamil Lambert, PhD" <Jamil.Lambert@proton.me>
Date: Wed, 3 Jul 2024 17:46:40 +0100
Subject: [PATCH 3/4] Standardize error headings

Created headings for a couple of function error descriptions to be
consistent with the rest of the crate.

Added a description explaining why Mega is not allowed in a
denomination.
---
 units/src/amount.rs | 32 +++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/units/src/amount.rs b/units/src/amount.rs
index 9290d9e22..09bb866f3 100644
--- a/units/src/amount.rs
+++ b/units/src/amount.rs
@@ -18,6 +18,19 @@ use internals::write_err;
 
 /// A set of denominations in which amounts can be expressed.
 ///
+/// # Accepted Denominations
+///
+/// All upper or lower case, excluding SI prefix (c, m, u) which must be lower case.
+/// - Singular: BTC, cBTC, mBTC, uBTC
+/// - Plural or singular: sat, satoshi, bit
+///
+/// # Note
+///
+/// Due to ambiguity between mega and milli we prohibit usage of leading capital 'M'.  It is
+/// more important to protect users from incorrectly using a capital M to mean milli than to
+/// allow Megabitcoin which is not a realistic denomination, and Megasatoshi which is
+/// equivalent to cBTC which is allowed.
+///
 /// # Examples
 ///
 /// ```
@@ -107,13 +120,12 @@ impl FromStr for Denomination {
 
     /// Converts from a `str` to a `Denomination`.
     ///
-    /// # Accepted Denominations
+    /// # Errors
     ///
-    /// All upper or lower case, excluding SI prefix (c, m, u) which must be lower case.
-    /// - Singular: BTC, cBTC, mBTC, uBTC
-    /// - Plural or singular: sat, satoshi, bit
+    /// - If the denomination begins with a capital `M` a `PossiblyConfusingDenominationError` is
+    ///   returned.
     ///
-    /// Due to ambiguity between mega and milli we prohibit usage of leading capital 'M'.
+    /// - If an unknown denomination is used, an `UnknownDenominationError` is returned.
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         use self::ParseDenominationError::*;
 
@@ -946,7 +958,10 @@ impl Amount {
 
     /// Converts this [`Amount`] in floating-point notation with a given
     /// denomination.
-    /// Can return error if the amount is too big, too precise or negative.
+    ///
+    /// # Errors
+    ///
+    /// If the amount is too big, too precise or negative.
     ///
     /// Please be aware of the risk of using floating-point numbers.
     #[cfg(feature = "alloc")]
@@ -1302,7 +1317,10 @@ impl SignedAmount {
 
     /// Convert this [`SignedAmount`] in floating-point notation with a given
     /// denomination.
-    /// Can return error if the amount is too big, too precise or negative.
+    ///
+    /// # Errors
+    ///
+    /// If the amount is too big, too precise or negative.
     ///
     /// Please be aware of the risk of using floating-point numbers.
     #[cfg(feature = "alloc")]

From 6dd5af9678c40cac9e360dfcbd9623cdb774c755 Mon Sep 17 00:00:00 2001
From: "Jamil Lambert, PhD" <Jamil.Lambert@proton.me>
Date: Wed, 3 Jul 2024 17:58:57 +0100
Subject: [PATCH 4/4] Add missing links

The use of links in the rustdocs was inconsistent.

Links have been added when missing.

[`locktime::absolute::Height`] and [`locktime::relative::Height`] did
not work and `(crate::locktime)` was appended to fix it.
---
 units/src/amount.rs            | 18 +++++++++---------
 units/src/block.rs             | 20 ++++++++++----------
 units/src/fee_rate.rs          | 20 ++++++++++----------
 units/src/locktime/absolute.rs | 10 +++++-----
 units/src/locktime/relative.rs |  2 +-
 units/src/weight.rs            | 26 +++++++++++++-------------
 6 files changed, 48 insertions(+), 48 deletions(-)

diff --git a/units/src/amount.rs b/units/src/amount.rs
index 09bb866f3..d32cce72d 100644
--- a/units/src/amount.rs
+++ b/units/src/amount.rs
@@ -122,10 +122,10 @@ impl FromStr for Denomination {
     ///
     /// # Errors
     ///
-    /// - If the denomination begins with a capital `M` a `PossiblyConfusingDenominationError` is
+    /// - If the denomination begins with a capital `M` a [`PossiblyConfusingDenominationError`] is
     ///   returned.
     ///
-    /// - If an unknown denomination is used, an `UnknownDenominationError` is returned.
+    /// - If an unknown denomination is used, an [`UnknownDenominationError`] is returned.
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         use self::ParseDenominationError::*;
 
@@ -525,7 +525,7 @@ fn is_too_precise(s: &str, precision: usize) -> Option<usize> {
 const INPUT_STRING_LEN_LIMIT: usize = 50;
 
 /// Parses a decimal string in the given denomination into a satoshi value and a
-/// `bool` indicator for a negative amount.
+/// [`bool`] indicator for a negative amount.
 fn parse_signed_to_satoshi(
     mut s: &str,
     denom: Denomination,
@@ -1017,7 +1017,7 @@ impl Amount {
         self.display_in(denom).show_denomination().to_string()
     }
 
-    // Some arithmetic that doesn't fit in `core::ops` traits.
+    // Some arithmetic that doesn't fit in [`core::ops`] traits.
 
     /// Checked addition.
     ///
@@ -1173,13 +1173,13 @@ impl core::iter::Sum for Amount {
 
 /// A helper/builder that displays amount with specified settings.
 ///
-/// This provides richer interface than `fmt::Formatter`:
+/// This provides richer interface than [`fmt::Formatter`]:
 ///
 /// * Ability to select denomination
 /// * Show or hide denomination
 /// * Dynamically-selected denomination - show in sats if less than 1 BTC.
 ///
-/// However this can still be combined with `fmt::Formatter` options to precisely control zeros,
+/// However this can still be combined with [`fmt::Formatter`] options to precisely control zeros,
 /// padding, alignment... The formatting works like floats from `core` but note that precision will
 /// **never** be lossy - that means no rounding.
 ///
@@ -1376,12 +1376,12 @@ impl SignedAmount {
         self.display_in(denom).show_denomination().to_string()
     }
 
-    // Some arithmetic that doesn't fit in `core::ops` traits.
+    // Some arithmetic that doesn't fit in [`core::ops`] traits.
 
     /// Get the absolute value of this [`SignedAmount`].
     pub fn abs(self) -> SignedAmount { SignedAmount(self.0.abs()) }
 
-    /// Get the absolute value of this [`SignedAmount`] returning `Amount`.
+    /// Get the absolute value of this [`SignedAmount`] returning [`Amount`].
     pub fn unsigned_abs(self) -> Amount { Amount(self.0.unsigned_abs()) }
 
     /// Returns a number representing sign of this [`SignedAmount`].
@@ -1593,7 +1593,7 @@ impl core::iter::Sum for SignedAmount {
 /// Calculates the sum over the iterator using checked arithmetic.
 pub trait CheckedSum<R>: private::SumSeal<R> {
     /// Calculates the sum over the iterator using checked arithmetic. If an over or underflow would
-    /// happen it returns `None`.
+    /// happen it returns [`None`].
     fn checked_sum(self) -> Option<R>;
 }
 
diff --git a/units/src/block.rs b/units/src/block.rs
index b79023135..659458010 100644
--- a/units/src/block.rs
+++ b/units/src/block.rs
@@ -65,10 +65,10 @@ impl From<BlockHeight> for u32 {
 }
 
 impl From<absolute::Height> for BlockHeight {
-    /// Converts [`locktime::absolute::Height`] to a [`BlockHeight`].
+    /// Converts a [`locktime::absolute::Height`] to a [`BlockHeight`].
     ///
-    /// An absolute locktime block height has a maximum value of `absolute::LOCK_TIME_THRESHOLD`
-    /// (500,000,000) where as a `BlockHeight` is a thin wrapper around a `u32`, the two types are
+    /// An absolute locktime block height has a maximum value of [`absolute::LOCK_TIME_THRESHOLD`]
+    /// (500,000,000) where as a [`BlockHeight`] is a thin wrapper around a `u32`, the two types are
     /// not interchangeable.
     fn from(h: absolute::Height) -> Self { Self::from_u32(h.to_consensus_u32()) }
 }
@@ -76,10 +76,10 @@ impl From<absolute::Height> for BlockHeight {
 impl TryFrom<BlockHeight> for absolute::Height {
     type Error = absolute::ConversionError;
 
-    /// Converts [`BlockHeight`] to a [`locktime::absolute::Height`].
+    /// Converts a [`BlockHeight`] to a [`locktime::absolute::Height`].
     ///
-    /// An absolute locktime block height has a maximum value of `absolute::LOCK_TIME_THRESHOLD`
-    /// (500,000,000) where as a `BlockHeight` is a thin wrapper around a `u32`, the two types are
+    /// An absolute locktime block height has a maximum value of [`absolute::LOCK_TIME_THRESHOLD`]
+    /// (500,000,000) where as a [`BlockHeight`] is a thin wrapper around a `u32`, the two types are
     /// not interchangeable.
     fn try_from(h: BlockHeight) -> Result<Self, Self::Error> {
         absolute::Height::from_consensus(h.to_u32())
@@ -132,20 +132,20 @@ impl From<BlockInterval> for u32 {
 }
 
 impl From<relative::Height> for BlockInterval {
-    /// Converts [`locktime::relative::Height`] to a [`BlockInterval`].
+    /// Converts a [`locktime::relative::Height`] to a [`BlockInterval`].
     ///
     /// A relative locktime block height has a maximum value of `u16::MAX` where as a
-    /// `BlockInterval` is a thin wrapper around a `u32`, the two types are not interchangeable.
+    /// [`BlockInterval`] is a thin wrapper around a `u32`, the two types are not interchangeable.
     fn from(h: relative::Height) -> Self { Self::from_u32(h.value().into()) }
 }
 
 impl TryFrom<BlockInterval> for relative::Height {
     type Error = TooBigForRelativeBlockHeightError;
 
-    /// Converts [`BlockInterval`] to a [`locktime::relative::Height`].
+    /// Converts a [`BlockInterval`] to a [`locktime::relative::Height`].
     ///
     /// A relative locktime block height has a maximum value of `u16::MAX` where as a
-    /// `BlockInterval` is a thin wrapper around a `u32`, the two types are not interchangeable.
+    /// [`BlockInterval`] is a thin wrapper around a `u32`, the two types are not interchangeable.
     fn try_from(h: BlockInterval) -> Result<Self, Self::Error> {
         let h = h.to_u32();
         if h > u16::MAX as u32 {
diff --git a/units/src/fee_rate.rs b/units/src/fee_rate.rs
index 648f34707..901f9ce65 100644
--- a/units/src/fee_rate.rs
+++ b/units/src/fee_rate.rs
@@ -42,14 +42,14 @@ impl FeeRate {
     /// Fee rate used to compute dust amount.
     pub const DUST: FeeRate = FeeRate::from_sat_per_vb_unchecked(3);
 
-    /// Constructs `FeeRate` from satoshis per 1000 weight units.
+    /// Constructs [`FeeRate`] from satoshis per 1000 weight units.
     pub const fn from_sat_per_kwu(sat_kwu: u64) -> Self { FeeRate(sat_kwu) }
 
-    /// Constructs `FeeRate` from satoshis per virtual bytes.
+    /// Constructs [`FeeRate`] from satoshis per virtual bytes.
     ///
     /// # Errors
     ///
-    /// Returns `None` on arithmetic overflow.
+    /// Returns [`None`] on arithmetic overflow.
     pub fn from_sat_per_vb(sat_vb: u64) -> Option<Self> {
         // 1 vb == 4 wu
         // 1 sat/vb == 1/4 sat/wu
@@ -57,7 +57,7 @@ impl FeeRate {
         Some(FeeRate(sat_vb.checked_mul(1000 / 4)?))
     }
 
-    /// Constructs `FeeRate` from satoshis per virtual bytes without overflow check.
+    /// Constructs [`FeeRate`] from satoshis per virtual bytes without overflow check.
     pub const fn from_sat_per_vb_unchecked(sat_vb: u64) -> Self { FeeRate(sat_vb * (1000 / 4)) }
 
     /// Returns raw fee rate.
@@ -73,34 +73,34 @@ impl FeeRate {
 
     /// Checked multiplication.
     ///
-    /// Computes `self * rhs` returning `None` if overflow occurred.
+    /// Computes `self * rhs` returning [`None`] if overflow occurred.
     pub fn checked_mul(self, rhs: u64) -> Option<Self> { self.0.checked_mul(rhs).map(Self) }
 
     /// Checked division.
     ///
-    /// Computes `self / rhs` returning `None` if `rhs == 0`.
+    /// Computes `self / rhs` returning [`None`] if `rhs == 0`.
     pub fn checked_div(self, rhs: u64) -> Option<Self> { self.0.checked_div(rhs).map(Self) }
 
     /// Checked weight multiplication.
     ///
     /// Computes the absolute fee amount for a given [`Weight`] at this fee rate.
     ///
-    /// `None` is returned if an overflow occurred.
+    /// [`None`] is returned if an overflow occurred.
     pub fn checked_mul_by_weight(self, rhs: Weight) -> Option<Amount> {
         let sats = self.0.checked_mul(rhs.to_wu())?.checked_add(999)? / 1000;
         Some(Amount::from_sat(sats))
     }
 
-    /// Calculates the fee by multiplying this fee rate by weight, in weight units, returning `None`
+    /// Calculates the fee by multiplying this fee rate by weight, in weight units, returning [`None`]
     /// if an overflow occurred.
     ///
     /// This is equivalent to `Self::checked_mul_by_weight()`.
     pub fn fee_wu(self, weight: Weight) -> Option<Amount> { self.checked_mul_by_weight(weight) }
 
-    /// Calculates the fee by multiplying this fee rate by weight, in virtual bytes, returning `None`
+    /// Calculates the fee by multiplying this fee rate by weight, in virtual bytes, returning [`None`]
     /// if an overflow occurred.
     ///
-    /// This is equivalent to converting `vb` to `weight` using `Weight::from_vb` and then calling
+    /// This is equivalent to converting `vb` to [`Weight`] using [`Weight::from_vb`] and then calling
     /// `Self::fee_wu(weight)`.
     pub fn fee_vb(self, vb: u64) -> Option<Amount> {
         Weight::from_vb(vb).and_then(|w| self.fee_wu(w))
diff --git a/units/src/locktime/absolute.rs b/units/src/locktime/absolute.rs
index 8eb2f95f5..ae8d468a4 100644
--- a/units/src/locktime/absolute.rs
+++ b/units/src/locktime/absolute.rs
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! Provides `Height` and `Time` types used by the `rust-bitcoin` `absolute::LockTime` type.
+//! Provides [`Height`] and [`Time`] types used by the `rust-bitcoin` `absolute::LockTime` type.
 
 use core::fmt;
 
@@ -39,7 +39,7 @@ impl Height {
     /// The maximum absolute block height.
     pub const MAX: Self = Height(LOCK_TIME_THRESHOLD - 1);
 
-    /// Creates a `Height` from a hex string.
+    /// Creates a [`Height`] from a hex string.
     ///
     /// The input string may or may not contain a typical hex prefix e.g., `0x`.
     pub fn from_hex(s: &str) -> Result<Self, ParseHeightError> {
@@ -70,7 +70,7 @@ impl Height {
         }
     }
 
-    /// Converts this `Height` to its inner `u32` value.
+    /// Converts this [`Height`] to its inner `u32` value.
     #[inline]
     pub fn to_consensus_u32(self) -> u32 { self.0 }
 }
@@ -137,7 +137,7 @@ impl Time {
     /// The maximum absolute block time (Sun Feb 07 2106 06:28:15 GMT+0000).
     pub const MAX: Self = Time(u32::MAX);
 
-    /// Creates a `Time` from a hex string.
+    /// Creates a [`Time`] from a hex string.
     ///
     /// The input string may or may not contain a typical hex prefix e.g., `0x`.
     pub fn from_hex(s: &str) -> Result<Self, ParseTimeError> { parse_hex(s, Self::from_consensus) }
@@ -166,7 +166,7 @@ impl Time {
         }
     }
 
-    /// Converts this `Time` to its inner `u32` value.
+    /// Converts this [`Time`] to its inner `u32` value.
     #[inline]
     pub fn to_consensus_u32(self) -> u32 { self.0 }
 }
diff --git a/units/src/locktime/relative.rs b/units/src/locktime/relative.rs
index fae92901e..b8c9a8d32 100644
--- a/units/src/locktime/relative.rs
+++ b/units/src/locktime/relative.rs
@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! Provides `Height` and `Time` types used by the `rust-bitcoin` `relative::LockTime` type.
+//! Provides [`Height`] and [`Time`] types used by the `rust-bitcoin` `relative::LockTime` type.
 
 use core::fmt;
 
diff --git a/units/src/weight.rs b/units/src/weight.rs
index 1740c36c2..956c1129c 100644
--- a/units/src/weight.rs
+++ b/units/src/weight.rs
@@ -13,7 +13,7 @@ pub const WITNESS_SCALE_FACTOR: usize = 4;
 
 /// Represents block weight - the weight of a transaction or block.
 ///
-/// This is an integer newtype representing weigth in `wu`. It provides protection against mixing
+/// This is an integer newtype representing [`Weight`] in `wu`. It provides protection against mixing
 /// up the types as well as basic formatting features.
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
@@ -43,21 +43,21 @@ impl Weight {
     /// The minimum transaction weight for a valid serialized transaction.
     pub const MIN_TRANSACTION: Weight = Weight(Self::WITNESS_SCALE_FACTOR * 60);
 
-    /// Directly constructs `Weight` from weight units.
+    /// Directly constructs [`Weight`] from weight units.
     pub const fn from_wu(wu: u64) -> Self { Weight(wu) }
 
-    /// Directly constructs `Weight` from usize weight units.
+    /// Directly constructs [`Weight`] from usize weight units.
     pub const fn from_wu_usize(wu: usize) -> Self { Weight(wu as u64) }
 
-    /// Constructs `Weight` from kilo weight units returning `None` if an overflow occurred.
+    /// Constructs [`Weight`] from kilo weight units returning [`None`] if an overflow occurred.
     pub fn from_kwu(wu: u64) -> Option<Self> { wu.checked_mul(1000).map(Weight) }
 
-    /// Constructs `Weight` from virtual bytes, returning `None` if an overflow occurred.
+    /// Constructs [`Weight`] from virtual bytes, returning [`None`] if an overflow occurred.
     pub fn from_vb(vb: u64) -> Option<Self> {
         vb.checked_mul(Self::WITNESS_SCALE_FACTOR).map(Weight::from_wu)
     }
 
-    /// Constructs `Weight` from virtual bytes panicking if an overflow occurred.
+    /// Constructs [`Weight`] from virtual bytes panicking if an overflow occurred.
     ///
     /// # Panics
     ///
@@ -76,13 +76,13 @@ impl Weight {
         }
     }
 
-    /// Constructs `Weight` from virtual bytes without an overflow check.
+    /// Constructs [`Weight`] from virtual bytes without an overflow check.
     pub const fn from_vb_unchecked(vb: u64) -> Self { Weight::from_wu(vb * 4) }
 
-    /// Constructs `Weight` from witness size.
+    /// Constructs [`Weight`] from witness size.
     pub const fn from_witness_data_size(witness_size: u64) -> Self { Weight(witness_size) }
 
-    /// Constructs `Weight` from non-witness size.
+    /// Constructs [`Weight`] from non-witness size.
     pub const fn from_non_witness_data_size(non_witness_size: u64) -> Self {
         Weight(non_witness_size * Self::WITNESS_SCALE_FACTOR)
     }
@@ -105,22 +105,22 @@ impl Weight {
 
     /// Checked addition.
     ///
-    /// Computes `self + rhs` returning `None` if an overflow occurred.
+    /// Computes `self + rhs` returning [`None`] if an overflow occurred.
     pub fn checked_add(self, rhs: Self) -> Option<Self> { self.0.checked_add(rhs.0).map(Self) }
 
     /// Checked subtraction.
     ///
-    /// Computes `self - rhs` returning `None` if an overflow occurred.
+    /// Computes `self - rhs` returning [`None`] if an overflow occurred.
     pub fn checked_sub(self, rhs: Self) -> Option<Self> { self.0.checked_sub(rhs.0).map(Self) }
 
     /// Checked multiplication.
     ///
-    /// Computes `self * rhs` returning `None` if an overflow occurred.
+    /// Computes `self * rhs` returning [`None`] if an overflow occurred.
     pub fn checked_mul(self, rhs: u64) -> Option<Self> { self.0.checked_mul(rhs).map(Self) }
 
     /// Checked division.
     ///
-    /// Computes `self / rhs` returning `None` if `rhs == 0`.
+    /// Computes `self / rhs` returning [`None`] if `rhs == 0`.
     pub fn checked_div(self, rhs: u64) -> Option<Self> { self.0.checked_div(rhs).map(Self) }
 }