From 02b523a8ada3e1bc9e78d5c011e0fd98603d5028 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sat, 7 Jun 2025 14:44:51 +0100 Subject: [PATCH 1/4] Remove whitespace from encapsulate module Whitespace here is unnecessary. Whitespace only, no logic change. --- units/src/weight.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/units/src/weight.rs b/units/src/weight.rs index 6649b4d64..6b4607eac 100644 --- a/units/src/weight.rs +++ b/units/src/weight.rs @@ -16,7 +16,6 @@ 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 From c87f7292beb65f96413124a611a5b59276ceb1e7 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sat, 7 Jun 2025 14:46:48 +0100 Subject: [PATCH 2/4] Fix rustdocs on Weight There is no point linking to `Weight` in the rustdocs of `Weight`. Also `wu` does not exist in this context, prefer 'weight units'. --- units/src/weight.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/units/src/weight.rs b/units/src/weight.rs index 6b4607eac..c59c18393 100644 --- a/units/src/weight.rs +++ b/units/src/weight.rs @@ -18,7 +18,7 @@ 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. #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] pub struct Weight(u64); From 153a6a2f3cff89f5545042868b4c804cd19382e3 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sat, 7 Jun 2025 14:58:11 +0100 Subject: [PATCH 3/4] Make Weight docs uniform with FeeRate --- units/src/weight.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/units/src/weight.rs b/units/src/weight.rs index c59c18393..31da7274c 100644 --- a/units/src/weight.rs +++ b/units/src/weight.rs @@ -19,7 +19,7 @@ mod encapsulate { /// The weight of a transaction or block. /// /// 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); @@ -37,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); From 7fbe07a6e0b3e398aca845d64ec86f3f0068edf4 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Sat, 7 Jun 2025 15:36:28 +0100 Subject: [PATCH 4/4] Use uniform docs for overflow Trivial change but make all the docs (rustdocs and code comments) use the same phrase when describing overflow. --- units/src/block.rs | 16 ++++++++-------- units/src/fee_rate/mod.rs | 19 +++++++++---------- units/src/locktime/absolute.rs | 6 +++--- 3 files changed, 20 insertions(+), 21 deletions(-) diff --git a/units/src/block.rs b/units/src/block.rs index c4a02cd9a..c7e61ce80 100644 --- a/units/src/block.rs +++ b/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 { self.0.checked_sub(other.0).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.0.checked_add(other.0).map(Self) @@ -148,11 +148,11 @@ 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.0.checked_sub(other.0).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.0.checked_add(other.0).map(Self) } } @@ -220,13 +220,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 { self.0.checked_sub(other.0).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.0.checked_add(other.0).map(Self) @@ -313,11 +313,11 @@ 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.0.checked_sub(other.0).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.0.checked_add(other.0).map(Self) } } diff --git a/units/src/fee_rate/mod.rs b/units/src/fee_rate/mod.rs index c2ee6f4b9..f0db11cf0 100644 --- a/units/src/fee_rate/mod.rs +++ b/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 { // 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. - /// - /// # Errors - /// - /// Returns [`None`] on arithmetic overflow. + /// Constructs a new [`FeeRate`] from satoshis per virtual bytes, + /// returning `None` if overflow occurred. pub const fn from_sat_per_vb(sat_vb: u64) -> Option { // 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 { // 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 { // 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 { // 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 { // No `map()` in const context. diff --git a/units/src/locktime/absolute.rs b/units/src/locktime/absolute.rs index cfbce396b..73102af8d 100644 --- a/units/src/locktime/absolute.rs +++ b/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;