units: Add Errors section to rustdocs

In `units` we lint for the `# Errors` section but in `primitives` we
don't so during recent code move from `primitives` to `units` we
introduced a bunch of lint warnings.

Add docs and clear all lint warnings.

Author: tcharding

units/src/locktime/absolute/mod.rs

@@ -112,6 +112,11 @@ impl LockTime {
 
     /// Constructs a new `LockTime` from a prefixed hex string.
     ///
+    /// # Errors
+    ///
+    /// If the input string is not a valid hex representation of a locktime or it does not include
+    /// the `0x` prefix.
+    ///
     /// # Examples
     ///
     /// ```
@@ -130,6 +135,11 @@ impl LockTime {
 
     /// Constructs a new `LockTime` from an unprefixed hex string.
     ///
+    /// # Errors
+    ///
+    /// If the input string is not a valid hex representation of a locktime or if it includes the
+    /// `0x` prefix.
+    ///
     /// # Examples
     ///
     /// ```
@@ -177,6 +187,11 @@ impl LockTime {
     ///
     /// See [`LOCK_TIME_THRESHOLD`] for definition of a valid height value.
     ///
+    /// # Errors
+    ///
+    /// If `n` does not represent a block height within the valid range for a locktime:
+    /// `[0, 499_999_999]`.
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -209,6 +224,10 @@ impl LockTime {
     ///
     /// See [`LOCK_TIME_THRESHOLD`] for definition of a valid time value.
     ///
+    /// # Errors
+    ///
+    /// If `n` is not in the allowable range of MTPs in a locktime: `[500_000_000, 2^32 - 1]`.
+    ///
     /// # Examples
     ///
     /// ```rust

units/src/locktime/relative/mod.rs

@@ -61,6 +61,10 @@ impl LockTime {
     /// locktimes only use some bits of the underlying `u32` value and discard the rest. If
     /// you want to preserve the full value, you should use the [`Sequence`] type instead.
     ///
+    /// # Errors
+    ///
+    /// If `n`, interpreted as a [`Sequence`] number does not encode a relative lock time.
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -106,6 +110,11 @@ impl LockTime {
     ///
     /// This method will **not** round-trip with [`Self::to_sequence`]. See the
     /// docs for [`Self::from_consensus`] for more information.
+    ///
+    /// # Errors
+    ///
+    /// If `n` does not encode a relative lock time.
+    ///
     /// # Examples
     ///
     /// ```rust

units/src/sequence.rs

@@ -122,13 +122,23 @@ impl Sequence {
     }
 
     /// Constructs a new `Sequence` from a prefixed hex string.
+    ///
+    /// # Errors
+    ///
+    /// If the input string is not a valid hex representation of a locktime or it does not include
+    /// the `0x` prefix.
     #[inline]
     pub fn from_hex(s: &str) -> Result<Self, PrefixedHexError> {
         let lock_time = parse::hex_u32_prefixed(s)?;
         Ok(Self::from_consensus(lock_time))
     }
 
     /// Constructs a new `Sequence` from an unprefixed hex string.
+    ///
+    /// # Errors
+    ///
+    /// If the input string is not a valid hex representation of a locktime or if it includes the
+    /// `0x` prefix.
     #[inline]
     pub fn from_unprefixed_hex(s: &str) -> Result<Self, UnprefixedHexError> {
         let lock_time = parse::hex_u32_unprefixed(s)?;
@@ -152,6 +162,11 @@ impl Sequence {
     /// interval with floor division.
     ///
     /// Will return an error if the input cannot be encoded in 16 bits.
+    ///
+    /// # Errors
+    ///
+    /// Will return an error if `seconds` cannot be encoded in 16 bits. See
+    /// [`NumberOf512Seconds::from_seconds_floor`].
     #[inline]
     pub fn from_seconds_floor(seconds: u32) -> Result<Self, TimeOverflowError> {
         let intervals = NumberOf512Seconds::from_seconds_floor(seconds)?;
@@ -162,6 +177,11 @@ impl Sequence {
     /// interval with ceiling division.
     ///
     /// Will return an error if the input cannot be encoded in 16 bits.
+    ///
+    /// # Errors
+    ///
+    /// Will return an error if `seconds` cannot be encoded in 16 bits. See
+    /// [`NumberOf512Seconds::from_seconds_ceil`].
     #[inline]
     pub fn from_seconds_ceil(seconds: u32) -> Result<Self, TimeOverflowError> {
         let intervals = NumberOf512Seconds::from_seconds_ceil(seconds)?;