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`)
This commit is contained in:
Tobin C. Harding 2024-10-31 11:47:50 +11:00
parent 41c80cc476
commit 5bec76aa51
No known key found for this signature in database
GPG Key ID: 40BF9E4C269D6607
2 changed files with 38 additions and 33 deletions

View File

@ -46,13 +46,13 @@ impl SignedAmount {
/// The maximum value of an amount. /// The maximum value of an amount.
pub const MAX: SignedAmount = SignedAmount(i64::MAX); 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) } pub const fn from_sat(satoshi: i64) -> SignedAmount { SignedAmount(satoshi) }
/// Gets the number of satoshis in this [`SignedAmount`]. /// Gets the number of satoshis in this [`SignedAmount`].
pub const fn to_sat(self) -> i64 { self.0 } 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")] #[cfg(feature = "alloc")]
pub fn from_btc(btc: f64) -> Result<SignedAmount, ParseAmountError> { pub fn from_btc(btc: f64) -> Result<SignedAmount, ParseAmountError> {
SignedAmount::from_float_in(btc, Denomination::Bitcoin) 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 /// Note: This only parses the value string. If you want to parse a value
/// with denomination, use [`FromStr`]. /// with denomination, use [`FromStr`].
@ -105,10 +105,10 @@ impl SignedAmount {
} }
} }
/// Parses amounts with denomination suffix like they are produced with /// Parses amounts with denomination suffix as produced by [`Self::to_string_with_denomination`]
/// [`Self::to_string_with_denomination`] or with [`fmt::Display`]. /// or with [`fmt::Display`].
/// If you want to parse only the amount without the denomination, ///
/// use [`Self::from_str_in`]. /// 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<SignedAmount, ParseError> { pub fn from_str_with_denomination(s: &str) -> Result<SignedAmount, ParseError> {
let (amt, denom) = split_amount_and_denomination(s)?; let (amt, denom) = split_amount_and_denomination(s)?;
SignedAmount::from_str_in(amt, denom).map_err(Into::into) 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. /// 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. /// 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")] #[cfg(feature = "alloc")]
pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) } 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) 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 { pub fn display_in(self, denomination: Denomination) -> Display {
Display { Display {
sats_abs: self.unsigned_abs().to_sat(), 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 /// This will use BTC for values greater than or equal to 1 BTC and satoshis otherwise. To
/// avoid confusion the denomination is always shown. /// 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. /// Does not include the denomination.
#[rustfmt::skip] #[rustfmt::skip]
@ -178,14 +184,14 @@ impl SignedAmount {
fmt_satoshi_in(self.unsigned_abs().to_sat(), self.is_negative(), f, denom, false, FormatOptions::default()) 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. /// Does not include the denomination.
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() } 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, /// Returns a formatted string representing this [`Amount`] in the given denomination, suffixed
/// suffixed with the abbreviation for the denomination. /// with the abbreviation for the denomination.
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn to_string_with_denomination(self, denom: Denomination) -> String { pub fn to_string_with_denomination(self, denom: Denomination) -> String {
self.display_in(denom).show_denomination().to_string() self.display_in(denom).show_denomination().to_string()
@ -196,7 +202,7 @@ impl SignedAmount {
/// Get the absolute value of this [`SignedAmount`]. /// Get the absolute value of this [`SignedAmount`].
pub fn abs(self) -> SignedAmount { SignedAmount(self.0.abs()) } 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()) } pub fn unsigned_abs(self) -> Amount { Amount::from_sat(self.0.unsigned_abs()) }
/// Returns a number representing sign of this [`SignedAmount`]. /// Returns a number representing sign of this [`SignedAmount`].
@ -248,8 +254,7 @@ impl SignedAmount {
/// Checked integer division. /// Checked integer division.
/// ///
/// Be aware that integer division loses the remainder if no exact division /// Be aware that integer division loses the remainder if no exact division can be made.
/// can be made.
/// ///
/// Returns [`None`] if overflow occurred. /// Returns [`None`] if overflow occurred.
pub fn checked_div(self, rhs: i64) -> Option<SignedAmount> { pub fn checked_div(self, rhs: i64) -> Option<SignedAmount> {
@ -395,8 +400,8 @@ impl FromStr for SignedAmount {
/// ///
/// # Returns /// # Returns
/// ///
/// `Ok(Amount)` if the string amount and denomination parse successfully, /// The amount if the string amount and denomination parse successfully,
/// otherwise, return `Err(ParseError)`. /// otherwise returns `Err(ParseError)`.
fn from_str(s: &str) -> Result<Self, Self::Err> { fn from_str(s: &str) -> Result<Self, Self::Err> {
let result = SignedAmount::from_str_with_denomination(s); let result = SignedAmount::from_str_with_denomination(s);

View File

@ -62,7 +62,7 @@ impl Amount {
/// Gets the number of satoshis in this [`Amount`]. /// Gets the number of satoshis in this [`Amount`].
pub const fn to_sat(self) -> u64 { self.0 } 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")] #[cfg(feature = "alloc")]
pub fn from_btc(btc: f64) -> Result<Amount, ParseAmountError> { pub fn from_btc(btc: f64) -> Result<Amount, ParseAmountError> {
Amount::from_float_in(btc, Denomination::Bitcoin) Amount::from_float_in(btc, Denomination::Bitcoin)
@ -111,10 +111,10 @@ impl Amount {
Ok(Amount::from_sat(satoshi)) Ok(Amount::from_sat(satoshi))
} }
/// Parses amounts with denomination suffix like they are produced with /// Parses amounts with denomination suffix as produced by [`Self::to_string_with_denomination`]
/// [`Self::to_string_with_denomination`] or with [`fmt::Display`]. /// or with [`fmt::Display`].
/// If you want to parse only the amount without the denomination, ///
/// use [`Self::from_str_in`]. /// 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<Amount, ParseError> { pub fn from_str_with_denomination(s: &str) -> Result<Amount, ParseError> {
let (amt, denom) = split_amount_and_denomination(s)?; let (amt, denom) = split_amount_and_denomination(s)?;
Amount::from_str_in(amt, denom).map_err(Into::into) 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()) 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. /// Does not include the denomination.
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() } 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, /// Returns a formatted string representing this [`Amount`] in the given denomination, suffixed
/// suffixed with the abbreviation for the denomination. /// with the abbreviation for the denomination.
#[cfg(feature = "alloc")] #[cfg(feature = "alloc")]
pub fn to_string_with_denomination(self, denom: Denomination) -> String { pub fn to_string_with_denomination(self, denom: Denomination) -> String {
self.display_in(denom).show_denomination().to_string() self.display_in(denom).show_denomination().to_string()
@ -226,8 +226,8 @@ impl Amount {
/// Checked integer division. /// Checked integer division.
/// ///
/// Be aware that integer division loses the remainder if no exact division /// Be aware that integer division loses the remainder if no exact division can be made.
/// 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) } pub fn checked_div(self, rhs: u64) -> Option<Amount> { 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 /// can be made. This method rounds up ensuring the transaction fee-rate is
/// sufficient. If you wish to round down use `amount / weight`. /// 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")] #[cfg(feature = "alloc")]
pub fn checked_div_by_weight(self, rhs: Weight) -> Option<FeeRate> { pub fn checked_div_by_weight(self, rhs: Weight) -> Option<FeeRate> {
let sats = self.0.checked_mul(1000)?; let sats = self.0.checked_mul(1000)?;
@ -365,8 +365,8 @@ impl FromStr for Amount {
/// ///
/// # Returns /// # Returns
/// ///
/// `Ok(Amount)` if the string amount and denomination parse successfully, /// The amount if the string amount and denomination parse successfully,
/// otherwise, return `Err(ParseError)`. /// otherwise returns `Err(ParseError)`.
fn from_str(s: &str) -> Result<Self, Self::Err> { fn from_str(s: &str) -> Result<Self, Self::Err> {
let result = Amount::from_str_with_denomination(s); let result = Amount::from_str_with_denomination(s);