Fix rustdoc grammar

In the rustdocs, made all function descriptions third person. Corrected
some grammar and improved some wording.

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<usize> {
 
 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, ParseAmountError> {
         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<SignedAmount, OutOfRangeError> {
         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<SignedAmount> { self.0.checked_abs().map(SignedAmount) }
 
     /// Checked addition.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_add(self, rhs: SignedAmount) -> Option<SignedAmount> {
         self.0.checked_add(rhs.0).map(SignedAmount)
     }
 
     /// Checked subtraction.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
         self.0.checked_sub(rhs.0).map(SignedAmount)
     }
 
     /// Checked multiplication.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_mul(self, rhs: i64) -> Option<SignedAmount> {
         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<SignedAmount> {
         self.0.checked_div(rhs).map(SignedAmount)
     }
 
     /// Checked remainder.
+    ///
     /// Returns [`None`] if overflow occurred.
     pub fn checked_rem(self, rhs: i64) -> Option<SignedAmount> {
         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<SignedAmount> {
         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<Amount, OutOfRangeError> {
         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<R>: private::SumSeal<R> {
-    /// 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<R>;
 }

units/src/block.rs

@@ -155,7 +155,7 @@ impl TryFrom<BlockInterval> 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);
 

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`
+    /// Calculates the fee by multiplying this fee rate by weight, in weight units, returning `None`
-    /// if overflow occurred.
+    /// if an overflow occurred.
     ///
     /// This is equivalent to `Self::checked_mul_by_weight()`.
     pub fn fee_wu(self, weight: Weight) -> Option<Amount> { self.checked_mul_by_weight(weight) }
 
-    /// Calculates fee by multiplying this fee rate by weight, in virtual bytes, returning `None`
+    /// Calculates the fee by multiplying this fee rate by weight, in virtual bytes, returning `None`
-    /// if overflow occurred.
+    /// 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<FeeRate> 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<FeeRate> for Weight {
     type Output = Amount;
 

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<Self, ParseHeightError> {
         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<Self, ParseTimeError> { parse_hex(s, Self::from_consensus) }
 
     /// Constructs a new block time.

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
+    /// Creates a [`Time`] from seconds, converting the seconds into 512 second intervals with
-    /// division.
+    /// ceiling division.
     ///
     /// # Errors
     ///

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<u32, ParseIntError> {
 ///
 /// # Errors
 ///
-/// - If input string does not contain a `0x` (or `0X`) prefix.
+/// - If the 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 is not a valid hex encoding of a `u32`.
 pub fn hex_u32_prefixed(s: &str) -> Result<u32, PrefixedHexError> {
     let checked = hex_remove_prefix(s)?;
     Ok(hex_u32_unchecked(checked)?)
@@ -214,19 +214,19 @@ pub fn hex_u32_prefixed(s: &str) -> Result<u32, PrefixedHexError> {
 ///
 /// # Errors
 ///
-/// - If input string contains a `0x` (or `0X`) prefix.
+/// - If the input string contains a `0x` (or `0X`) prefix.
-/// - If input string is not a valid hex encoding of a `u32`.
+/// - If the input string is not a valid hex encoding of a `u32`.
 pub fn hex_u32_unprefixed(s: &str) -> Result<u32, UnprefixedHexError> {
     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`.
+/// - If the input string contains a `0x` (or `0X`) prefix, returns `InvalidDigit` due to the `x`.
-/// - With `InvalidDigit` due to the `x` if there is a prefix.
+/// - If the input string is not a valid hex encoding of a `u32`.
 pub fn hex_u32_unchecked(s: &str) -> Result<u32, ParseIntError> {
     u32::from_str_radix(s, 16).map_err(|error| ParseIntError {
         input: s.into(),
@@ -252,8 +252,8 @@ pub fn hex_u128(s: &str) -> Result<u128, ParseIntError> {
 ///
 /// # Errors
 ///
-/// - If input string does not contain a `0x` (or `0X`) prefix.
+/// - If the 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 is not a valid hex encoding of a `u128`.
 pub fn hex_u128_prefixed(s: &str) -> Result<u128, PrefixedHexError> {
     let checked = hex_remove_prefix(s)?;
     Ok(hex_u128_unchecked(checked)?)
@@ -263,19 +263,19 @@ pub fn hex_u128_prefixed(s: &str) -> Result<u128, PrefixedHexError> {
 ///
 /// # Errors
 ///
-/// - If input string contains a `0x` (or `0X`) prefix.
+/// - If the input string contains a `0x` (or `0X`) prefix.
-/// - If input string is not a valid hex encoding of a `u128`.
+/// - If the input string is not a valid hex encoding of a `u128`.
 pub fn hex_u128_unprefixed(s: &str) -> Result<u128, UnprefixedHexError> {
     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`.
+/// - If the input string contains a `0x` (or `0X`) prefix, returns `InvalidDigit` due to the `x`.
-/// - With `InvalidDigit` due to the `x` if there is a prefix.
+/// - If the input string is not a valid hex encoding of a `u128`.
 pub fn hex_u128_unchecked(s: &str) -> Result<u128, ParseIntError> {
     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
+/// Error returned when parsing an integer from a hex string that is supposed to contain a prefix.
-/// a type that can be created infallibly from an integer.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum PrefixedHexError {
     /// Hex string is missing prefix.
@@ -337,7 +336,7 @@ impl From<ParseIntError> 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<ParseIntError> 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,

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<Self> { 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<Self> {
         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
     ///