From 5bec76aa51c3183c20165ee5af892b8d057a3da8 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 31 Oct 2024 11:47:50 +1100 Subject: [PATCH] amount: Fix rustdocs Fix the rustdocs on `Amount` and `SignedAmount` by doing: - Make them uniform - Use correct style (looks like `SignedAmount` got left behind when we improved `Amount`) --- units/src/amount/signed.rs | 45 ++++++++++++++++++++---------------- units/src/amount/unsigned.rs | 26 ++++++++++----------- 2 files changed, 38 insertions(+), 33 deletions(-) diff --git a/units/src/amount/signed.rs b/units/src/amount/signed.rs index 30f43a3f1..7c3490e11 100644 --- a/units/src/amount/signed.rs +++ b/units/src/amount/signed.rs @@ -46,13 +46,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. + /// Creates a [`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 const fn to_sat(self) -> i64 { self.0 } - /// Convert from a value expressing bitcoins to a [`SignedAmount`]. + /// Converts from a value expressing a whole number of bitcoin to a [`SignedAmount`]. #[cfg(feature = "alloc")] pub fn from_btc(btc: f64) -> Result { SignedAmount::from_float_in(btc, Denomination::Bitcoin) @@ -88,7 +88,7 @@ impl SignedAmount { } } - /// 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`]. @@ -105,10 +105,10 @@ impl SignedAmount { } } - /// Parses amounts with denomination suffix like they are produced with - /// [`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`]. + /// Parses amounts with denomination suffix as produced by [`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`]. pub fn from_str_with_denomination(s: &str) -> Result { let (amt, denom) = split_amount_and_denomination(s)?; SignedAmount::from_str_in(amt, denom).map_err(Into::into) @@ -124,9 +124,15 @@ impl SignedAmount { /// Express this [`SignedAmount`] as a floating-point value in Bitcoin. /// - /// Equivalent to `to_float_in(Denomination::Bitcoin)`. - /// /// Please be aware of the risk of using floating-point numbers. + /// + /// # Examples + /// + /// ``` + /// # use bitcoin_units::amount::{SignedAmount, Denomination}; + /// let amount = SignedAmount::from_sat(100_000); + /// assert_eq!(amount.to_btc(), amount.to_float_in(Denomination::Bitcoin)) + /// ``` #[cfg(feature = "alloc")] pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) } @@ -148,7 +154,7 @@ impl SignedAmount { SignedAmount::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.unsigned_abs().to_sat(), @@ -157,7 +163,7 @@ impl SignedAmount { } } - /// 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. @@ -169,7 +175,7 @@ impl SignedAmount { } } - /// Format the value of this [`SignedAmount`] in the given denomination. + /// Formats the value of this [`SignedAmount`] in the given denomination. /// /// Does not include the denomination. #[rustfmt::skip] @@ -178,14 +184,14 @@ 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. + /// Returns a formatted string representing 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, - /// suffixed with the abbreviation for the denomination. + /// Returns a formatted string representing 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 { self.display_in(denom).show_denomination().to_string() @@ -196,7 +202,7 @@ impl 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`]. + /// Gets the absolute value of this [`SignedAmount`] returning [`Amount`]. pub fn unsigned_abs(self) -> Amount { Amount::from_sat(self.0.unsigned_abs()) } /// Returns a number representing sign of this [`SignedAmount`]. @@ -248,8 +254,7 @@ impl SignedAmount { /// Checked integer division. /// - /// Be aware that integer division loses the remainder if no exact division - /// can be made. + /// 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 { @@ -395,8 +400,8 @@ impl FromStr for SignedAmount { /// /// # Returns /// - /// `Ok(Amount)` if the string amount and denomination parse successfully, - /// otherwise, return `Err(ParseError)`. + /// The amount if the string amount and denomination parse successfully, + /// otherwise returns `Err(ParseError)`. fn from_str(s: &str) -> Result { let result = SignedAmount::from_str_with_denomination(s); diff --git a/units/src/amount/unsigned.rs b/units/src/amount/unsigned.rs index 5efefb426..cbc9f07ef 100644 --- a/units/src/amount/unsigned.rs +++ b/units/src/amount/unsigned.rs @@ -62,7 +62,7 @@ impl Amount { /// Gets the number of satoshis in this [`Amount`]. pub const fn to_sat(self) -> u64 { self.0 } - /// Converts from a value expressing bitcoins to an [`Amount`]. + /// Converts from a value expressing a whole number of bitcoin to an [`Amount`]. #[cfg(feature = "alloc")] pub fn from_btc(btc: f64) -> Result { Amount::from_float_in(btc, Denomination::Bitcoin) @@ -111,10 +111,10 @@ impl Amount { Ok(Amount::from_sat(satoshi)) } - /// Parses amounts with denomination suffix like they are produced with - /// [`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`]. + /// Parses amounts with denomination suffix as produced by [`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`]. pub fn from_str_with_denomination(s: &str) -> Result { let (amt, denom) = split_amount_and_denomination(s)?; Amount::from_str_in(amt, denom).map_err(Into::into) @@ -190,14 +190,14 @@ impl Amount { fmt_satoshi_in(self.to_sat(), false, f, denom, false, FormatOptions::default()) } - /// Returns a formatted string of this [`Amount`] in the given denomination. + /// Returns a formatted string representing 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() } - /// Returns a formatted string of this [`Amount`] in the given denomination, - /// suffixed with the abbreviation for the denomination. + /// Returns a formatted string representing 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 { self.display_in(denom).show_denomination().to_string() @@ -226,8 +226,8 @@ impl Amount { /// Checked integer division. /// - /// Be aware that integer division loses the remainder if no exact division - /// can be made. + /// 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: u64) -> Option { self.0.checked_div(rhs).map(Amount) } @@ -237,7 +237,7 @@ impl Amount { /// can be made. This method rounds up ensuring the transaction fee-rate is /// sufficient. If you wish to round down use `amount / weight`. /// - /// [`None`] is returned if an overflow occurred. + /// Returns [`None`] if overflow occurred. #[cfg(feature = "alloc")] pub fn checked_div_by_weight(self, rhs: Weight) -> Option { let sats = self.0.checked_mul(1000)?; @@ -365,8 +365,8 @@ impl FromStr for Amount { /// /// # Returns /// - /// `Ok(Amount)` if the string amount and denomination parse successfully, - /// otherwise, return `Err(ParseError)`. + /// The amount if the string amount and denomination parse successfully, + /// otherwise returns `Err(ParseError)`. fn from_str(s: &str) -> Result { let result = Amount::from_str_with_denomination(s);