Merge rust-bitcoin/rust-bitcoin#3929: Polish `units::parse` docs

7ca5c5ccae Fix rustdoc title on hex_u128_* (Tobin C. Harding)
f1e2564821 Improve docs on parse::int_from_string (Tobin C. Harding)
d97cbc6d27 units: Correct docs on private Sealed trait (Tobin C. Harding)

Pull request description:

  Audit the `units::parse` module checking for sanity of the API. Could still possibly do with more improvements to the docs but for the `1.0-alpha` this is good to go IMO.

  Close: #3710

ACKs for top commit:
  apoelstra:
    ACK 7ca5c5ccae1efe5862f21bfc670257837a202517; successfully ran local tests; looks good!

Tree-SHA512: 937e8f6e1ae0a17217b770daffe1968ec9046c86728a360f1297d7027318511fece31440f462fdaeb94c2a69901a970e20bd2599a6d963bfbdf06b25378fe543

units/src/parse.rs

@@ -71,12 +71,17 @@ macro_rules! impl_integer {
 impl_integer!(u8, i8, u16, i16, u32, i32, u64, i64, u128, i128);
 
 mod sealed {
-    /// Seals the extension traits.
+    /// Seals the `Integer` trait.
     pub trait Sealed {}
 }
 
 /// Parses the input string as an integer returning an error carrying rich context.
 ///
+/// Apart from the rich error context this function exists so that we can handle builds with and
+/// without an allocator. If an allocator is available (`alloc` feature enabled) then this function
+/// allocates to copy the input string into the error return. If `alloc` is not enabled the input
+/// string is lost.
+///
 /// If the caller has a `String` or `Box<str>` which is not used later it's better to call
 /// [`parse::int_from_string`] or [`parse::int_from_box`] respectively.
 ///
@@ -331,7 +336,7 @@ pub fn hex_u128(s: &str) -> Result<u128, ParseIntError> {
     Ok(hex_u128_unchecked(unchecked)?)
 }
 
-/// Parses a `u128` from a hex string.
+/// Parses a `u128` from a prefixed hex string.
 ///
 /// # Errors
 ///
@@ -342,7 +347,7 @@ pub fn hex_u128_prefixed(s: &str) -> Result<u128, PrefixedHexError> {
     Ok(hex_u128_unchecked(checked)?)
 }
 
-/// Parses a `u128` from a hex string.
+/// Parses a `u128` from an unprefixed hex string.
 ///
 /// # Errors
 ///