From ebc6b4a876112f76a9f2cf33edb758ff05fb284f Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Mon, 14 Apr 2025 13:56:00 +0100 Subject: [PATCH 1/3] Make warning text bold --- units/src/amount/signed.rs | 2 +- units/src/amount/unsigned.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/units/src/amount/signed.rs b/units/src/amount/signed.rs index 7070adf77..3bd4d5b90 100644 --- a/units/src/amount/signed.rs +++ b/units/src/amount/signed.rs @@ -25,7 +25,7 @@ mod encapsulate { /// conversion to various denominations. The [`SignedAmount`] type does not implement [`serde`] /// traits but we do provide modules for serializing as satoshis or bitcoin. /// - /// Warning! + /// **Warning!** /// /// This type implements several arithmetic operations from [`core::ops`]. /// To prevent errors due to an overflow when using these operations, diff --git a/units/src/amount/unsigned.rs b/units/src/amount/unsigned.rs index 20bb6f82b..4a1d875b0 100644 --- a/units/src/amount/unsigned.rs +++ b/units/src/amount/unsigned.rs @@ -25,7 +25,7 @@ mod encapsulate { /// conversion to various denominations. The [`Amount`] type does not implement [`serde`] traits /// but we do provide modules for serializing as satoshis or bitcoin. /// - /// Warning! + /// **Warning!** /// /// This type implements several arithmetic operations from [`core::ops`]. /// To prevent errors due to an overflow when using these operations, From afe9ddd5e63d063ec07a4cc4f47c72d0cb909c74 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Mon, 14 Apr 2025 13:58:04 +0100 Subject: [PATCH 2/3] Remove - in fee rate The rest of the rustdocs use fee rate with no hyphen when using it in normal language, i.e. not a function argument or the type. Change it to match the others. --- units/src/fee.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/units/src/fee.rs b/units/src/fee.rs index c44bc8966..86f4a5b5c 100644 --- a/units/src/fee.rs +++ b/units/src/fee.rs @@ -19,7 +19,7 @@ impl Amount { /// Checked weight ceiling division. /// /// 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 + /// can be made. This method rounds up ensuring the transaction fee rate is /// sufficient. See also [`Self::checked_div_by_weight_floor`]. /// /// Returns [`None`] if overflow occurred. From 913360b112673ed35dc70e22a1d3566b6f22dfc4 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Mon, 14 Apr 2025 15:43:57 +0100 Subject: [PATCH 3/3] Make struct titles consistent Structs had various phrasings of titles. Make the wording consistent by concisely stating what it is, instead of what it does. Make the wording of all error structs consistent. --- units/src/amount/error.rs | 4 ++-- units/src/fee_rate/mod.rs | 2 +- units/src/locktime/absolute.rs | 2 +- units/src/locktime/relative.rs | 2 +- units/src/result.rs | 2 +- units/src/weight.rs | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/units/src/amount/error.rs b/units/src/amount/error.rs index 2c91392b4..dd06db041 100644 --- a/units/src/amount/error.rs +++ b/units/src/amount/error.rs @@ -10,7 +10,7 @@ use internals::write_err; use super::INPUT_STRING_LEN_LIMIT; -/// An error during amount parsing amount with denomination. +/// Error returned when parsing an amount with denomination fails. #[derive(Debug, Clone, PartialEq, Eq)] pub struct ParseError(pub(crate) ParseErrorInner); @@ -84,7 +84,7 @@ impl std::error::Error for ParseError { } } -/// An error during amount parsing. +/// Error returned when parsing an amount fails. #[derive(Debug, Clone, PartialEq, Eq)] pub struct ParseAmountError(pub(crate) ParseAmountErrorInner); diff --git a/units/src/fee_rate/mod.rs b/units/src/fee_rate/mod.rs index 0daafa2d2..709e3f988 100644 --- a/units/src/fee_rate/mod.rs +++ b/units/src/fee_rate/mod.rs @@ -10,7 +10,7 @@ use core::{fmt, ops}; #[cfg(feature = "arbitrary")] use arbitrary::{Arbitrary, Unstructured}; -/// Represents fee rate. +/// Fee rate. /// /// This is an integer newtype representing fee rate in `sat/kwu`. It provides protection against /// mixing up the types as well as basic formatting features. diff --git a/units/src/locktime/absolute.rs b/units/src/locktime/absolute.rs index 698516078..153aa0e33 100644 --- a/units/src/locktime/absolute.rs +++ b/units/src/locktime/absolute.rs @@ -256,7 +256,7 @@ pub const fn is_block_height(n: u32) -> bool { n < LOCK_TIME_THRESHOLD } /// Returns true if `n` is a UNIX timestamp i.e., greater than or equal to 500,000,000. pub const fn is_block_time(n: u32) -> bool { n >= LOCK_TIME_THRESHOLD } -/// An error that occurs when converting a `u32` to a lock time variant. +/// Error returned when converting a `u32` to a lock time variant fails. #[derive(Debug, Clone, PartialEq, Eq)] #[non_exhaustive] pub struct ConversionError { diff --git a/units/src/locktime/relative.rs b/units/src/locktime/relative.rs index 7f8b4413a..9b1abadf7 100644 --- a/units/src/locktime/relative.rs +++ b/units/src/locktime/relative.rs @@ -128,7 +128,7 @@ impl fmt::Display for Time { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fmt::Display::fmt(&self.0, f) } } -/// Input time in seconds was too large to be encoded to a 16 bit 512 second interval. +/// Error returned when the input time in seconds was too large to be encoded to a 16 bit 512 second interval. #[derive(Debug, Clone, PartialEq, Eq)] pub struct TimeOverflowError { /// Time value in seconds that overflowed. diff --git a/units/src/result.rs b/units/src/result.rs index 8276e6cc1..97d6fefae 100644 --- a/units/src/result.rs +++ b/units/src/result.rs @@ -127,7 +127,7 @@ macro_rules! impl_opt_ext { } impl_opt_ext!(Amount, SignedAmount, u64, i64, FeeRate, Weight); -/// An error occurred while doing a mathematical operation. +/// Error returned when a mathematical operation fails. #[derive(Debug, Copy, Clone, PartialEq, Eq)] #[non_exhaustive] pub struct NumOpError(MathOp); diff --git a/units/src/weight.rs b/units/src/weight.rs index 50c08df97..22aea3836 100644 --- a/units/src/weight.rs +++ b/units/src/weight.rs @@ -12,7 +12,7 @@ use serde::{Deserialize, Serialize}; /// The factor that non-witness serialization data is multiplied by during weight calculation. pub const WITNESS_SCALE_FACTOR: usize = 4; -/// Represents weight - the weight of a transaction or block. +/// The weight of a transaction or block. /// /// This is an integer newtype representing [`Weight`] in `wu`. It provides protection against mixing /// up types as well as basic formatting features.