Merge rust-bitcoin/rust-bitcoin#4606: units: Improve docs

7fbe07a6e0 Use uniform docs for overflow (Tobin C. Harding)
153a6a2f3c Make Weight docs uniform with FeeRate (Tobin C. Harding)
c87f7292be Fix rustdocs on Weight (Tobin C. Harding)
02b523a8ad Remove whitespace from encapsulate module (Tobin C. Harding)

Pull request description:

  Make a sweep of the `units` crate's rustdocs.

ACKs for top commit:
  apoelstra:
    ACK 7fbe07a6e0b3e398aca845d64ec86f3f0068edf4; successfully ran local tests

Tree-SHA512: ba50f3afb94dda43f89d04eb53c6e85df302292d4647fe81a20e3f7d1ca75e8ee8cdf6548864b2f3c33ed661205d109dbd763db1061ea45a59eab25f134191f8

units/src/block.rs

@@ -87,13 +87,13 @@ impl BlockHeight {
     /// Returns block height as a `u32`.
     pub const fn to_u32(self) -> u32 { self.0 }
 
-    /// Attempt to subtract two [`BlockHeight`]s, returning `None` in case of overflow.
+    /// Attempt to subtract two [`BlockHeight`]s, returning `None` if overflow occurred.
     #[must_use]
     pub fn checked_sub(self, other: Self) -> Option<BlockHeightInterval> {
         self.to_u32().checked_sub(other.to_u32()).map(BlockHeightInterval)
     }
 
-    /// Attempt to add an interval to this [`BlockHeight`], returning `None` in case of overflow.
+    /// Attempt to add an interval to this [`BlockHeight`], returning `None` if overflow occurred.
     #[must_use]
     pub fn checked_add(self, other: BlockHeightInterval) -> Option<Self> {
         self.to_u32().checked_add(other.to_u32()).map(Self)
@@ -148,13 +148,13 @@ impl BlockHeightInterval {
     /// Returns block interval as a `u32`.
     pub const fn to_u32(self) -> u32 { self.0 }
 
-    /// Attempt to subtract two [`BlockHeightInterval`]s, returning `None` in case of overflow.
+    /// Attempt to subtract two [`BlockHeightInterval`]s, returning `None` if overflow occurred.
     #[must_use]
     pub fn checked_sub(self, other: Self) -> Option<Self> {
         self.to_u32().checked_sub(other.to_u32()).map(Self)
     }
 
-    /// Attempt to add two [`BlockHeightInterval`]s, returning `None` in case of overflow.
+    /// Attempt to add two [`BlockHeightInterval`]s, returning `None` if overflow occurred.
     #[must_use]
     pub fn checked_add(self, other: Self) -> Option<Self> {
         self.to_u32().checked_add(other.to_u32()).map(Self)
@@ -224,13 +224,13 @@ impl BlockMtp {
         Self::from_u32(u32::from(timestamps[5]))
     }
 
-    /// Attempt to subtract two [`BlockMtp`]s, returning `None` in case of overflow.
+    /// Attempt to subtract two [`BlockMtp`]s, returning `None` if overflow occurred.
     #[must_use]
     pub fn checked_sub(self, other: Self) -> Option<BlockMtpInterval> {
         self.to_u32().checked_sub(other.to_u32()).map(BlockMtpInterval)
     }
 
-    /// Attempt to add an interval to this [`BlockMtp`], returning `None` in case of overflow.
+    /// Attempt to add an interval to this [`BlockMtp`], returning `None` if overflow occurred.
     #[must_use]
     pub fn checked_add(self, other: BlockMtpInterval) -> Option<Self> {
         self.to_u32().checked_add(other.to_u32()).map(Self)
@@ -317,13 +317,13 @@ impl BlockMtpInterval {
         relative::NumberOf512Seconds::from_seconds_ceil(self.to_u32())
     }
 
-    /// Attempt to subtract two [`BlockMtpInterval`]s, returning `None` in case of overflow.
+    /// Attempt to subtract two [`BlockMtpInterval`]s, returning `None` if overflow occurred.
     #[must_use]
     pub fn checked_sub(self, other: Self) -> Option<Self> {
         self.to_u32().checked_sub(other.to_u32()).map(Self)
     }
 
-    /// Attempt to add two [`BlockMtpInterval`]s, returning `None` in case of overflow.
+    /// Attempt to add two [`BlockMtpInterval`]s, returning `None` if overflow occurred.
     #[must_use]
     pub fn checked_add(self, other: Self) -> Option<Self> {
         self.to_u32().checked_add(other.to_u32()).map(Self)

units/src/fee_rate/mod.rs

@@ -52,7 +52,8 @@ impl FeeRate {
     /// The fee rate used to compute dust amount.
     pub const DUST: FeeRate = FeeRate::from_sat_per_vb_u32(3);
 
-    /// Constructs a new [`FeeRate`] from satoshis per 1000 weight units.
+    /// Constructs a new [`FeeRate`] from satoshis per 1000 weight units,
+    /// returning `None` if overflow occurred.
     pub const fn from_sat_per_kwu(sat_kwu: u64) -> Option<Self> {
         // No `map()` in const context.
         match sat_kwu.checked_mul(4_000) {
@@ -61,11 +62,8 @@ impl FeeRate {
         }
     }
 
-    /// Constructs a new [`FeeRate`] from satoshis per virtual bytes.
+    /// Constructs a new [`FeeRate`] from satoshis per virtual bytes,
-    ///
+    /// returning `None` if overflow occurred.
-    /// # Errors
-    ///
-    /// Returns [`None`] on arithmetic overflow.
     pub const fn from_sat_per_vb(sat_vb: u64) -> Option<Self> {
         // No `map()` in const context.
         match sat_vb.checked_mul(1_000_000) {
@@ -80,7 +78,8 @@ impl FeeRate {
         FeeRate::from_sat_per_mvb(sat_vb * 1_000_000)
     }
 
-    /// Constructs a new [`FeeRate`] from satoshis per kilo virtual bytes (1,000 vbytes).
+    /// Constructs a new [`FeeRate`] from satoshis per kilo virtual bytes (1,000 vbytes),
+    /// returning `None` if overflow occurred.
     pub const fn from_sat_per_kvb(sat_kvb: u64) -> Option<Self> {
         // No `map()` in const context.
         match sat_kvb.checked_mul(1_000) {
@@ -109,7 +108,7 @@ impl FeeRate {
 
     /// Checked multiplication.
     ///
-    /// Computes `self * rhs` returning [`None`] if overflow occurred.
+    /// Computes `self * rhs`, returning [`None`] if overflow occurred.
     #[must_use]
     pub const fn checked_mul(self, rhs: u64) -> Option<Self> {
         // No `map()` in const context.
@@ -133,7 +132,7 @@ impl FeeRate {
 
     /// Checked addition.
     ///
-    /// Computes `self + rhs` returning [`None`] if overflow occurred.
+    /// Computes `self + rhs` returning [`None`] is case of overflow.
     #[must_use]
     pub const fn checked_add(self, rhs: FeeRate) -> Option<Self> {
         // No `map()` in const context.
@@ -145,7 +144,7 @@ impl FeeRate {
 
     /// Checked subtraction.
     ///
-    /// Computes `self - rhs` returning [`None`] if overflow occurred.
+    /// Computes `self - rhs`, returning [`None`] if overflow occurred.
     #[must_use]
     pub const fn checked_sub(self, rhs: FeeRate) -> Option<Self> {
         // No `map()` in const context.

units/src/locktime/absolute.rs

@@ -114,7 +114,7 @@ impl fmt::Display for ParseHeightError {
 
 #[cfg(feature = "std")]
 impl std::error::Error for ParseHeightError {
-    // To be consistent with `write_err` we need to **not** return source in case of overflow
+    // To be consistent with `write_err` we need to **not** return source if overflow occurred
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { self.0.source() }
 }
 
@@ -239,7 +239,7 @@ impl fmt::Display for ParseTimeError {
 
 #[cfg(feature = "std")]
 impl std::error::Error for ParseTimeError {
-    // To be consistent with `write_err` we need to **not** return source in case of overflow
+    // To be consistent with `write_err` we need to **not** return source if overflow occurred
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { self.0.source() }
 }
 
@@ -398,7 +398,7 @@ impl ParseError {
         }
     }
 
-    // To be consistent with `write_err` we need to **not** return source in case of overflow
+    // To be consistent with `write_err` we need to **not** return source if overflow occurred
     #[cfg(feature = "std")]
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         use core::num::IntErrorKind;

units/src/weight.rs

@@ -16,11 +16,10 @@ use crate::CheckedSum;
 pub const WITNESS_SCALE_FACTOR: usize = 4;
 
 mod encapsulate {
-
     /// The weight of a transaction or block.
     ///
-    /// This is an integer newtype representing [`Weight`] in `wu`. It provides protection
+    /// This is an integer newtype representing weight in weight units. It provides protection
-    /// against mixing up types as well as basic formatting features.
+    /// against mixing up the types, conversion functions, and basic formatting.
     #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
     pub struct Weight(u64);
 
@@ -38,7 +37,7 @@ mod encapsulate {
 pub use encapsulate::Weight;
 
 impl Weight {
-    /// 0 wu.
+    /// Zero weight units (wu).
     ///
     /// Equivalent to [`MIN`](Self::MIN), may better express intent in some contexts.
     pub const ZERO: Weight = Weight::from_wu(0);