Merge rust-bitcoin/rust-bitcoin#4343: units: Go over the rendered docs for the whole crate

913360b112 Make struct titles consistent (Jamil Lambert, PhD)
afe9ddd5e6 Remove - in fee rate (Jamil Lambert, PhD)
ebc6b4a876 Make warning text bold (Jamil Lambert, PhD)

Pull request description:

  I have read through all of the `units` docs and made a few changes.

  - Highlight `Warning!` in bold in `Amount` and `SignedAmount`

  - Change the one occurrence of fee-rate to fee rate to be consistent with the rest.

  - Make all of the error structs have the same title format of `Error returned...`

  - Make all other structs have the same format concisely stating what it is opposed to what it does.

ACKs for top commit:
  tcharding:
    ACK 913360b112

Tree-SHA512: 4cb08d1dae091f5b827cf9f1e931b057c6670002146a22da54886148f3052f6ea7050fcd7f62c0d83438ef170e2f109c1a36f47a280808f31466da6f3177dd01

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);
 

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,

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,

units/src/fee.rs

@@ -21,7 +21,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.

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.

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 {

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.

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);

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.