From 75f317a689501a79eea6b04efcda28fa12ccfe46 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Wed, 3 Jul 2024 15:09:02 +0100 Subject: [PATCH] Fix rustdoc grammar In the rustdocs, made all function descriptions third person. Corrected some grammar and improved some wording. --- units/src/amount.rs | 62 +++++++++++++++++++++------------- units/src/block.rs | 2 +- units/src/fee_rate.rs | 10 +++--- units/src/locktime/absolute.rs | 6 ++-- units/src/locktime/relative.rs | 10 +++--- units/src/parse.rs | 45 ++++++++++++------------ units/src/weight.rs | 4 +-- 7 files changed, 76 insertions(+), 63 deletions(-) diff --git a/units/src/amount.rs b/units/src/amount.rs index 705b19ff5..9290d9e22 100644 --- a/units/src/amount.rs +++ b/units/src/amount.rs @@ -67,7 +67,7 @@ impl Denomination { } } - /// Returns stringly representation of this + /// Returns a string representation of this denomination. fn as_str(self) -> &'static str { match self { Denomination::Bitcoin => "BTC", @@ -105,7 +105,7 @@ impl fmt::Display for Denomination { impl FromStr for Denomination { type Err = ParseDenominationError; - /// Convert from a `str` to `Denomination`. + /// Converts from a `str` to a `Denomination`. /// /// # Accepted Denominations /// @@ -260,7 +260,7 @@ impl std::error::Error for ParseAmountError { } } -/// Returned when a parsed amount is too big or too small. +/// Error returned when a parsed amount is too big or too small. #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub struct OutOfRangeError { is_signed: bool, @@ -395,7 +395,7 @@ enum MissingDigitsKind { OnlyMinusSign, } -/// Returned when the input contains an invalid character. +/// Error returned when the input contains an invalid character. #[derive(Debug, Clone, PartialEq, Eq)] pub struct InvalidCharacterError { invalid_char: char, @@ -458,7 +458,7 @@ impl std::error::Error for ParseDenominationError { #[non_exhaustive] pub struct MissingDenominationError; -/// Parsing error, unknown denomination. +/// Error returned when parsing an unknown denomination. #[derive(Debug, Clone, PartialEq, Eq)] #[non_exhaustive] pub struct UnknownDenominationError(InputString); @@ -474,7 +474,7 @@ impl std::error::Error for UnknownDenominationError { fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { None } } -/// Parsing error, possibly confusing denomination. +/// Error returned when parsing a possibly confusing denomination. #[derive(Debug, Clone, PartialEq, Eq)] #[non_exhaustive] pub struct PossiblyConfusingDenominationError(InputString); @@ -512,7 +512,7 @@ fn is_too_precise(s: &str, precision: usize) -> Option { const INPUT_STRING_LEN_LIMIT: usize = 50; -/// Parse decimal string in the given denomination into a satoshi value and a +/// Parses a decimal string in the given denomination into a satoshi value and a /// `bool` indicator for a negative amount. fn parse_signed_to_satoshi( mut s: &str, @@ -867,19 +867,19 @@ impl Amount { /// The number of bytes that an amount contributes to the size of a transaction. pub const SIZE: usize = 8; // Serialized length of a u64. - /// Create an [`Amount`] with satoshi precision and the given number of satoshis. + /// Creates an [`Amount`] with satoshi precision and the given number of satoshis. pub const fn from_sat(satoshi: u64) -> Amount { Amount(satoshi) } /// Gets the number of satoshis in this [`Amount`]. pub fn to_sat(self) -> u64 { self.0 } - /// Convert from a value expressing bitcoins to an [`Amount`]. + /// Converts from a value expressing bitcoins to an [`Amount`]. #[cfg(feature = "alloc")] pub fn from_btc(btc: f64) -> Result { Amount::from_float_in(btc, Denomination::Bitcoin) } - /// Convert from a value expressing integer values of bitcoins to an [`Amount`] + /// Converts from a value expressing integer values of bitcoins to an [`Amount`] /// in const context. /// /// # Panics @@ -900,7 +900,7 @@ impl Amount { } } - /// 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`]. @@ -922,7 +922,7 @@ impl Amount { Amount::from_str_in(amt, denom).map_err(Into::into) } - /// Express this [`Amount`] as a floating-point value in the given denomination. + /// Expresses this [`Amount`] as a floating-point value in the given denomination. /// /// Please be aware of the risk of using floating-point numbers. #[cfg(feature = "alloc")] @@ -930,7 +930,7 @@ impl Amount { f64::from_str(&self.to_string_in(denom)).unwrap() } - /// Express this [`Amount`] as a floating-point value in Bitcoin. + /// Expresses this [`Amount`] as a floating-point value in Bitcoin. /// /// Please be aware of the risk of using floating-point numbers. /// @@ -944,7 +944,7 @@ impl Amount { #[cfg(feature = "alloc")] pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) } - /// Convert this [`Amount`] in floating-point notation with a given + /// Converts this [`Amount`] in floating-point notation with a given /// denomination. /// Can return error if the amount is too big, too precise or negative. /// @@ -959,7 +959,7 @@ impl Amount { Amount::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.to_sat(), @@ -968,7 +968,7 @@ impl Amount { } } - /// 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. @@ -980,7 +980,7 @@ impl Amount { } } - /// Format the value of this [`Amount`] in the given denomination. + /// Formats the value of this [`Amount`] in the given denomination. /// /// Does not include the denomination. #[rustfmt::skip] @@ -989,13 +989,13 @@ impl Amount { fmt_satoshi_in(self.to_sat(), false, f, denom, false, FormatOptions::default()) } - /// Get a string number of this [`Amount`] in the given denomination. + /// Returns a formatted string of 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() } - /// Get a formatted string of this [`Amount`] in the given denomination, + /// Returns a formatted string of 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 { @@ -1053,7 +1053,7 @@ impl Amount { /// On overflow, panics in debug mode, wraps in release mode. pub fn unchecked_sub(self, rhs: Amount) -> Amount { Self(self.0 - rhs.0) } - /// Convert to a signed amount. + /// Converts to a signed amount. pub fn to_signed(self) -> Result { if self.to_sat() > SignedAmount::MAX.to_sat() as u64 { Err(OutOfRangeError::too_big(true)) @@ -1373,45 +1373,58 @@ impl SignedAmount { /// - `-1` if the amount is negative pub fn signum(self) -> i64 { self.0.signum() } + /// Checks if this [`SignedAmount`] is positive. + /// /// Returns `true` if this [`SignedAmount`] is positive and `false` if /// this [`SignedAmount`] is zero or negative. pub fn is_positive(self) -> bool { self.0.is_positive() } + /// Checks if this [`SignedAmount`] is negative. + /// /// Returns `true` if this [`SignedAmount`] is negative and `false` if /// this [`SignedAmount`] is zero or positive. pub fn is_negative(self) -> bool { self.0.is_negative() } - /// Get the absolute value of this [`SignedAmount`]. + /// Returns the absolute value of this [`SignedAmount`]. + /// + /// Consider using `unsigned_abs` which is often more practical. + /// /// Returns [`None`] if overflow occurred. (`self == MIN`) pub fn checked_abs(self) -> Option { self.0.checked_abs().map(SignedAmount) } /// Checked addition. + /// /// Returns [`None`] if overflow occurred. pub fn checked_add(self, rhs: SignedAmount) -> Option { self.0.checked_add(rhs.0).map(SignedAmount) } /// Checked subtraction. + /// /// Returns [`None`] if overflow occurred. pub fn checked_sub(self, rhs: SignedAmount) -> Option { self.0.checked_sub(rhs.0).map(SignedAmount) } /// Checked multiplication. + /// /// Returns [`None`] if overflow occurred. pub fn checked_mul(self, rhs: i64) -> Option { self.0.checked_mul(rhs).map(SignedAmount) } /// Checked integer division. + /// /// 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 { self.0.checked_div(rhs).map(SignedAmount) } /// Checked remainder. + /// /// Returns [`None`] if overflow occurred. pub fn checked_rem(self, rhs: i64) -> Option { self.0.checked_rem(rhs).map(SignedAmount) @@ -1436,6 +1449,7 @@ impl SignedAmount { pub fn unchecked_sub(self, rhs: SignedAmount) -> SignedAmount { Self(self.0 - rhs.0) } /// Subtraction that doesn't allow negative [`SignedAmount`]s. + /// /// Returns [`None`] if either [`self`], `rhs` or the result is strictly negative. pub fn positive_sub(self, rhs: SignedAmount) -> Option { if self.is_negative() || rhs.is_negative() || rhs > self { @@ -1445,7 +1459,7 @@ impl SignedAmount { } } - /// Convert to an unsigned amount. + /// Converts to an unsigned amount. pub fn to_unsigned(self) -> Result { if self.is_negative() { Err(OutOfRangeError::negative()) @@ -1558,9 +1572,9 @@ impl core::iter::Sum for SignedAmount { } } -/// Calculate the sum over the iterator using checked arithmetic. +/// Calculates the sum over the iterator using checked arithmetic. pub trait CheckedSum: private::SumSeal { - /// Calculate the sum over the iterator using checked arithmetic. If an over or underflow would + /// Calculates the sum over the iterator using checked arithmetic. If an over or underflow would /// happen it returns `None`. fn checked_sum(self) -> Option; } diff --git a/units/src/block.rs b/units/src/block.rs index bd3989f68..b79023135 100644 --- a/units/src/block.rs +++ b/units/src/block.rs @@ -155,7 +155,7 @@ impl TryFrom for relative::Height { } } -/// The block interval is too big to be used as a relative lock time. +/// Error returned when the block interval is too big to be used as a relative lock time. #[derive(Debug, Clone, PartialEq, Eq)] pub struct TooBigForRelativeBlockHeightError(u32); diff --git a/units/src/fee_rate.rs b/units/src/fee_rate.rs index 9dcb88ddb..648f34707 100644 --- a/units/src/fee_rate.rs +++ b/units/src/fee_rate.rs @@ -91,14 +91,14 @@ impl FeeRate { Some(Amount::from_sat(sats)) } - /// Calculates fee by multiplying this fee rate by weight, in weight units, returning `None` - /// if overflow occurred. + /// Calculates the fee by multiplying this fee rate by weight, in weight units, returning `None` + /// if an overflow occurred. /// /// This is equivalent to `Self::checked_mul_by_weight()`. pub fn fee_wu(self, weight: Weight) -> Option { self.checked_mul_by_weight(weight) } - /// Calculates fee by multiplying this fee rate by weight, in virtual bytes, returning `None` - /// if overflow occurred. + /// Calculates the fee by multiplying this fee rate by weight, in virtual bytes, returning `None` + /// if an overflow occurred. /// /// This is equivalent to converting `vb` to `weight` using `Weight::from_vb` and then calling /// `Self::fee_wu(weight)`. @@ -122,7 +122,7 @@ impl From for u64 { fn from(value: FeeRate) -> Self { value.to_sat_per_kwu() } } -/// Computes ceiling so that fee computation is conservative. +/// Computes the ceiling so that the fee computation is conservative. impl Mul for Weight { type Output = Amount; diff --git a/units/src/locktime/absolute.rs b/units/src/locktime/absolute.rs index 64a5094ce..8eb2f95f5 100644 --- a/units/src/locktime/absolute.rs +++ b/units/src/locktime/absolute.rs @@ -1,6 +1,6 @@ // SPDX-License-Identifier: CC0-1.0 -//! Provides type `Height` and `Time` types used by the `rust-bitcoin` `absolute::LockTime` type. +//! Provides `Height` and `Time` types used by the `rust-bitcoin` `absolute::LockTime` type. use core::fmt; @@ -41,7 +41,7 @@ impl Height { /// Creates a `Height` from a hex string. /// - /// The input string is may or may not contain a typical hex prefix e.g., `0x`. + /// The input string may or may not contain a typical hex prefix e.g., `0x`. pub fn from_hex(s: &str) -> Result { parse_hex(s, Self::from_consensus) } @@ -139,7 +139,7 @@ impl Time { /// Creates a `Time` from a hex string. /// - /// The input string is may or may not contain a typical hex prefix e.g., `0x`. + /// The input string may or may not contain a typical hex prefix e.g., `0x`. pub fn from_hex(s: &str) -> Result { parse_hex(s, Self::from_consensus) } /// Constructs a new block time. diff --git a/units/src/locktime/relative.rs b/units/src/locktime/relative.rs index b756def2d..fae92901e 100644 --- a/units/src/locktime/relative.rs +++ b/units/src/locktime/relative.rs @@ -1,6 +1,6 @@ // SPDX-License-Identifier: CC0-1.0 -//! Provides type `Height` and `Time` types used by the `rust-bitcoin` `relative::LockTime` type. +//! Provides `Height` and `Time` types used by the `rust-bitcoin` `relative::LockTime` type. use core::fmt; @@ -64,13 +64,13 @@ impl Time { /// The maximum relative block time (33,554,432 seconds or approx 388 days). pub const MAX: Self = Time(u16::MAX); - /// Create a [`Time`] using time intervals where each interval is equivalent to 512 seconds. + /// Creates a [`Time`] using time intervals where each interval is equivalent to 512 seconds. /// /// Encoding finer granularity of time for relative lock-times is not supported in Bitcoin. #[inline] pub const fn from_512_second_intervals(intervals: u16) -> Self { Time(intervals) } - /// Create a [`Time`] from seconds, converting the seconds into 512 second interval with + /// Creates a [`Time`] from seconds, converting the seconds into 512 second interval with /// truncating division. /// /// # Errors @@ -87,8 +87,8 @@ impl Time { } } - /// Create a [`Time`] from seconds, converting the seconds into 512 second interval with ceiling - /// division. + /// Creates a [`Time`] from seconds, converting the seconds into 512 second intervals with + /// ceiling division. /// /// # Errors /// diff --git a/units/src/parse.rs b/units/src/parse.rs index bdce64262..1ba8fbb3a 100644 --- a/units/src/parse.rs +++ b/units/src/parse.rs @@ -160,11 +160,11 @@ macro_rules! impl_parse_str { } } -/// Removes the prefix `0x` (or `0X`) from hex string. +/// Removes the prefix `0x` (or `0X`) from a hex string. /// /// # Errors /// -/// If input string does not contain a prefix. +/// If the input string does not contain a prefix. pub fn hex_remove_prefix(s: &str) -> Result<&str, PrefixedHexError> { if let Some(checked) = s.strip_prefix("0x") { Ok(checked) @@ -175,11 +175,11 @@ pub fn hex_remove_prefix(s: &str) -> Result<&str, PrefixedHexError> { } } -/// Checks hex string does not have a prefix `0x` (or `0X`). +/// Checks a hex string does not have a prefix `0x` (or `0X`). /// /// # Errors /// -/// If input string contains a prefix. +/// If the input string contains a prefix. pub fn hex_check_unprefixed(s: &str) -> Result<&str, UnprefixedHexError> { if s.starts_with("0x") || s.starts_with("0X") { return Err(ContainsPrefixError::new(s.into()).into()); @@ -203,8 +203,8 @@ pub fn hex_u32(s: &str) -> Result { /// /// # Errors /// -/// - If input string does not contain a `0x` (or `0X`) prefix. -/// - If input string is not a valid hex encoding of a `u32`. +/// - If the input string does not contain a `0x` (or `0X`) prefix. +/// - If the input string is not a valid hex encoding of a `u32`. pub fn hex_u32_prefixed(s: &str) -> Result { let checked = hex_remove_prefix(s)?; Ok(hex_u32_unchecked(checked)?) @@ -214,19 +214,19 @@ pub fn hex_u32_prefixed(s: &str) -> Result { /// /// # Errors /// -/// - If input string contains a `0x` (or `0X`) prefix. -/// - If input string is not a valid hex encoding of a `u32`. +/// - If the input string contains a `0x` (or `0X`) prefix. +/// - If the input string is not a valid hex encoding of a `u32`. pub fn hex_u32_unprefixed(s: &str) -> Result { let checked = hex_check_unprefixed(s)?; Ok(hex_u32_unchecked(checked)?) } -/// Parses a `u32` from a hex string. +/// Parses a `u32` from an unprefixed hex string without first checking for a prefix. /// /// # Errors /// -/// - If input string is not a valid hex encoding of a `u32`. -/// - With `InvalidDigit` due to the `x` if there is a prefix. +/// - If the input string contains a `0x` (or `0X`) prefix, returns `InvalidDigit` due to the `x`. +/// - If the input string is not a valid hex encoding of a `u32`. pub fn hex_u32_unchecked(s: &str) -> Result { u32::from_str_radix(s, 16).map_err(|error| ParseIntError { input: s.into(), @@ -252,8 +252,8 @@ pub fn hex_u128(s: &str) -> Result { /// /// # Errors /// -/// - If input string does not contain a `0x` (or `0X`) prefix. -/// - If input string is not a valid hex encoding of a `u128`. +/// - If the input string does not contain a `0x` (or `0X`) prefix. +/// - If the input string is not a valid hex encoding of a `u128`. pub fn hex_u128_prefixed(s: &str) -> Result { let checked = hex_remove_prefix(s)?; Ok(hex_u128_unchecked(checked)?) @@ -263,19 +263,19 @@ pub fn hex_u128_prefixed(s: &str) -> Result { /// /// # Errors /// -/// - If input string contains a `0x` (or `0X`) prefix. -/// - If input string is not a valid hex encoding of a `u128`. +/// - If the input string contains a `0x` (or `0X`) prefix. +/// - If the input string is not a valid hex encoding of a `u128`. pub fn hex_u128_unprefixed(s: &str) -> Result { let checked = hex_check_unprefixed(s)?; Ok(hex_u128_unchecked(checked)?) } -/// Parses a `u128` from a hex string. +/// Parses a `u128` from an unprefixed hex string without first checking for a prefix. /// /// # Errors /// -/// - If input string is not a valid hex encoding of a `u128`. -/// - With `InvalidDigit` due to the `x` if there is a prefix. +/// - If the input string contains a `0x` (or `0X`) prefix, returns `InvalidDigit` due to the `x`. +/// - If the input string is not a valid hex encoding of a `u128`. pub fn hex_u128_unchecked(s: &str) -> Result { u128::from_str_radix(s, 16).map_err(|error| ParseIntError { input: s.into(), @@ -296,8 +296,7 @@ pub(crate) fn hex_remove_optional_prefix(s: &str) -> &str { } } -/// Error returned when parsing integer from an supposedly prefixed hex string for -/// a type that can be created infallibly from an integer. +/// Error returned when parsing an integer from a hex string that is supposed to contain a prefix. #[derive(Debug, Clone, Eq, PartialEq)] pub enum PrefixedHexError { /// Hex string is missing prefix. @@ -337,7 +336,7 @@ impl From for PrefixedHexError { fn from(e: ParseIntError) -> Self { Self::ParseInt(e) } } -/// Error returned when parsing integer from an supposedly un-prefixed hex string. +/// Error returned when parsing an integer from a hex string that is not supposed to contain a prefix. #[derive(Debug, Clone, Eq, PartialEq)] pub enum UnprefixedHexError { /// Hex string contains prefix. @@ -377,7 +376,7 @@ impl From for UnprefixedHexError { fn from(e: ParseIntError) -> Self { Self::ParseInt(e) } } -/// Error when hex string is missing a prefix (e.g. `0x`). +/// Error returned when a hex string is missing a prefix (e.g. `0x`). #[derive(Debug, Clone, Eq, PartialEq)] pub struct MissingPrefixError { hex: String, @@ -397,7 +396,7 @@ impl fmt::Display for MissingPrefixError { #[cfg(feature = "std")] impl std::error::Error for MissingPrefixError {} -/// Error when hex string contains a prefix (e.g. `0x`). +/// Error when hex string contains a prefix (e.g. 0x). #[derive(Debug, Clone, Eq, PartialEq)] pub struct ContainsPrefixError { hex: String, diff --git a/units/src/weight.rs b/units/src/weight.rs index 3153bf4d7..1740c36c2 100644 --- a/units/src/weight.rs +++ b/units/src/weight.rs @@ -52,12 +52,12 @@ impl Weight { /// Constructs `Weight` from kilo weight units returning `None` if an overflow occurred. pub fn from_kwu(wu: u64) -> Option { wu.checked_mul(1000).map(Weight) } - /// Constructs `Weight` from virtual bytes, returning `None` on overflow. + /// Constructs `Weight` from virtual bytes, returning `None` if an overflow occurred. pub fn from_vb(vb: u64) -> Option { vb.checked_mul(Self::WITNESS_SCALE_FACTOR).map(Weight::from_wu) } - /// Constructs `Weight` from virtual bytes panicking on overflow. + /// Constructs `Weight` from virtual bytes panicking if an overflow occurred. /// /// # Panics ///