From 09e184015ea1d69ea1935a30ed47ea963b64f19f Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Wed, 18 Dec 2024 15:54:43 +0000 Subject: [PATCH] Fix rustdocs in SignedAmount --- units/src/amount/signed.rs | 48 +++++++++++++++++++----------------- units/src/amount/unsigned.rs | 9 ++++--- 2 files changed, 31 insertions(+), 26 deletions(-) diff --git a/units/src/amount/signed.rs b/units/src/amount/signed.rs index a817566e2..8a0845edd 100644 --- a/units/src/amount/signed.rs +++ b/units/src/amount/signed.rs @@ -19,15 +19,15 @@ use super::{ /// A signed amount. /// /// The [`SignedAmount`] type can be used to express Bitcoin amounts that support arithmetic and -/// conversion to various denominations. The `Amount` type does not implement `serde` traits but we -/// do provide modules for serializing as satoshis or bitcoin. +/// conversion to various denominations. The [`SignedAmount`] type does not implement [`serde`] +/// traits but we do provide modules for serializing as satoshis or bitcoin. /// /// Warning! /// /// 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 [`SignedAmount`] /// implements will panic when overflow or underflow occurs. /// /// # Examples @@ -68,7 +68,7 @@ impl SignedAmount { /// Gets the number of satoshis in this [`SignedAmount`]. pub const fn to_sat(self) -> i64 { self.0 } - /// Converts from a value expressing a whole number of bitcoin to a [`SignedAmount`]. + /// Converts from a value expressing a decimal number of bitcoin to a [`SignedAmount`]. #[cfg(feature = "alloc")] pub fn from_btc(btc: f64) -> Result { SignedAmount::from_float_in(btc, Denomination::Bitcoin) @@ -101,10 +101,10 @@ impl SignedAmount { } } - /// Parses 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`]. + /// Note: This only parses the value string. If you want to parse a string + /// containing the value with denomination, use [`FromStr`]. pub fn from_str_in(s: &str, denom: Denomination) -> Result { match parse_signed_to_satoshi(s, denom).map_err(|error| error.convert(true))? { // (negative, amount) @@ -128,7 +128,7 @@ impl SignedAmount { SignedAmount::from_str_in(amt, denom).map_err(Into::into) } - /// Express this [`SignedAmount`] as a floating-point value in the given denomination. + /// Expresses 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")] @@ -136,7 +136,7 @@ impl SignedAmount { self.to_string_in(denom).parse::().unwrap() } - /// Express this [`SignedAmount`] as a floating-point value in Bitcoin. + /// Expresses this [`SignedAmount`] as a floating-point value in Bitcoin. /// /// Please be aware of the risk of using floating-point numbers. /// @@ -150,8 +150,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 - /// denomination. + /// Converts this [`SignedAmount`] in floating-point notation in the given [`Denomination`]. /// /// # Errors /// @@ -168,7 +167,9 @@ impl SignedAmount { SignedAmount::from_str_in(&value.to_string(), denom) } - /// Constructs a new object that implements [`fmt::Display`] using specified denomination. + /// Constructs a new object that implements [`fmt::Display`] in the given [`Denomination`]. + /// + /// This function is useful if you do not wish to allocate. See also [`Self::to_string_in`]. #[must_use] pub fn display_in(self, denomination: Denomination) -> Display { Display { @@ -178,7 +179,8 @@ impl SignedAmount { } } - /// Constructs a new object that implements [`fmt::Display`] dynamically selecting denomination. + /// Constructs a new 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. @@ -191,14 +193,14 @@ impl SignedAmount { } } - /// Returns a formatted string representing this [`SignedAmount`] in the given denomination. + /// Returns a formatted string representing this [`SignedAmount`] in the given [`Denomination`]. /// - /// Does not include the denomination. + /// Returned string does not include the denomination. #[cfg(feature = "alloc")] pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() } - /// Returns a formatted string representing this [`Amount`] in the given denomination, suffixed - /// with the abbreviation for the denomination. + /// Returns a formatted string representing 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 { self.display_in(denom).show_denomination().to_string() @@ -206,7 +208,7 @@ impl SignedAmount { // Some arithmetic that doesn't fit in [`core::ops`] traits. - /// Get the absolute value of this [`SignedAmount`]. + /// Gets the absolute value of this [`SignedAmount`]. #[must_use] pub fn abs(self) -> SignedAmount { SignedAmount(self.0.abs()) } @@ -238,7 +240,7 @@ impl SignedAmount { /// /// Consider using `unsigned_abs` which is often more practical. /// - /// Returns [`None`] if overflow occurred. (`self == MIN`) + /// Returns [`None`] if overflow occurred. (`self == i64::MIN`) #[must_use] pub const fn checked_abs(self) -> Option { // No `map()` in const context. @@ -250,7 +252,7 @@ impl SignedAmount { /// Checked addition. /// - /// Returns [`None`] if overflow occurred. + /// Returns [`None`] if the sum is above [`SignedAmount::MAX`] or below [`SignedAmount::MIN`]. #[must_use] pub const fn checked_add(self, rhs: SignedAmount) -> Option { // No `map()` in const context. @@ -262,7 +264,8 @@ impl SignedAmount { /// Checked subtraction. /// - /// Returns [`None`] if overflow occurred. + /// Returns [`None`] if the difference is above [`SignedAmount::MAX`] or below + /// [`SignedAmount::MIN`]. #[must_use] pub const fn checked_sub(self, rhs: SignedAmount) -> Option { // No `map()` in const context. @@ -274,7 +277,8 @@ impl SignedAmount { /// Checked multiplication. /// - /// Returns [`None`] if overflow occurred. + /// Returns [`None`] if the product is above [`SignedAmount::MAX`] or below + /// [`SignedAmount::MIN`]. #[must_use] pub const fn checked_mul(self, rhs: i64) -> Option { // No `map()` in const context. diff --git a/units/src/amount/unsigned.rs b/units/src/amount/unsigned.rs index be18ea8f2..bb2a3d3e6 100644 --- a/units/src/amount/unsigned.rs +++ b/units/src/amount/unsigned.rs @@ -199,8 +199,7 @@ impl Amount { #[cfg(feature = "alloc")] pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) } - /// Converts this [`Amount`] in floating-point notation in the given - /// [`Denomination`]. + /// Converts this [`Amount`] in floating-point notation in the given [`Denomination`]. /// /// # Errors /// @@ -218,6 +217,8 @@ impl Amount { } /// Constructs a new object that implements [`fmt::Display`] in the given [`Denomination`]. + /// + /// This function is useful if you do not wish to allocate. See also [`Self::to_string_in`]. #[must_use] pub fn display_in(self, denomination: Denomination) -> Display { Display { @@ -326,7 +327,7 @@ impl Amount { /// /// Be aware that integer division loses the remainder if no exact division /// can be made. This method rounds up ensuring the transaction fee-rate is - /// sufficient. See also [`Amount::checked_div_by_weight_floor`]. + /// sufficient. See also [`Self::checked_div_by_weight_floor`]. /// /// Returns [`None`] if overflow occurred. /// @@ -359,7 +360,7 @@ impl Amount { /// Checked weight floor division. /// /// Be aware that integer division loses the remainder if no exact division - /// can be made. See also [`Amount::checked_div_by_weight_ceil`]. + /// can be made. See also [`Self::checked_div_by_weight_ceil`]. /// /// Returns [`None`] if overflow occurred. #[cfg(feature = "alloc")]