Repository: rust-bitcoin/rust-bitcoin (language: rust)

Issue:
In rustdoc examples use e.g. `relative::LockTime` and `relative::Height` not import and use `LockTime` etc.
Users should be encouraged to explicitly use `relative::*` or `absolute::*` instead of just `LockTime`, `Time`, `Height` so that it is clear when looking at the code if it is a relative or absolute locktime.

Mentioned here: https://github.com/rust-bitcoin/rust-bitcoin/pull/3968#discussion_r1932821138

Change all the examples to fit this format.


Discussion / hints:
Mad, thanks.

Fix patch:
diff --git a/primitives/src/locktime/absolute.rs b/primitives/src/locktime/absolute.rs
index 976f56143c..ae924e26bc 100644
--- a/primitives/src/locktime/absolute.rs
+++ b/primitives/src/locktime/absolute.rs
@@ -42,9 +42,9 @@ pub use units::locktime::absolute::{ConversionError, Height, ParseHeightError, P
 /// # Examples
 ///
 /// ```
-/// # use bitcoin_primitives::absolute::{LockTime, LockTime::*};
-/// # let n = LockTime::from_consensus(741521);          // n OP_CHECKLOCKTIMEVERIFY
-/// # let lock_time = LockTime::from_consensus(741521);  // nLockTime
+/// # use bitcoin_primitives::absolute::{self, LockTime::*};
+/// # let n = absolute::LockTime::from_consensus(741521);          // n OP_CHECKLOCKTIMEVERIFY
+/// # let lock_time = absolute::LockTime::from_consensus(741521);  // nLockTime
 /// // To compare absolute lock times there are various `is_satisfied_*` methods, you may also use:
 /// let _is_satisfied = match (n, lock_time) {
 ///     (Blocks(n), Blocks(lock_time)) => n <= lock_time,
@@ -59,10 +59,10 @@ pub enum LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// use bitcoin_primitives::absolute::LockTime;
+    /// use bitcoin_primitives::absolute;
     ///
     /// let block: u32 = 741521;
-    /// let n = LockTime::from_height(block).expect("valid height");
+    /// let n = absolute::LockTime::from_height(block).expect("valid height");
     /// assert!(n.is_block_height());
     /// assert_eq!(n.to_consensus_u32(), block);
     /// ```
@@ -72,10 +72,10 @@ pub enum LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// use bitcoin_primitives::absolute::LockTime;
+    /// use bitcoin_primitives::absolute;
     ///
     /// let seconds: u32 = 1653195600; // May 22nd, 5am UTC.
-    /// let n = LockTime::from_time(seconds).expect("valid time");
+    /// let n = absolute::LockTime::from_time(seconds).expect("valid time");
     /// assert!(n.is_block_time());
     /// assert_eq!(n.to_consensus_u32(), seconds);
     /// ```
@@ -95,9 +95,9 @@ impl LockTime {
     /// # Examples
     ///
     /// ```
-    /// # use bitcoin_primitives::absolute::LockTime;
+    /// # use bitcoin_primitives::absolute;
     /// let hex_str = "0x61cf9980"; // Unix timestamp for January 1, 2022
-    /// let lock_time = LockTime::from_hex(hex_str)?;
+    /// let lock_time = absolute::LockTime::from_hex(hex_str)?;
     /// assert_eq!(lock_time.to_consensus_u32(), 0x61cf9980);
     ///
     /// # Ok::<_, units::parse::PrefixedHexError>(())
@@ -112,9 +112,9 @@ impl LockTime {
     /// # Examples
     ///
     /// ```
-    /// # use bitcoin_primitives::absolute::LockTime;
+    /// # use bitcoin_primitives::absolute;
     /// let hex_str = "61cf9980"; // Unix timestamp for January 1, 2022
-    /// let lock_time = LockTime::from_unprefixed_hex(hex_str)?;
+    /// let lock_time = absolute::LockTime::from_unprefixed_hex(hex_str)?;
     /// assert_eq!(lock_time.to_consensus_u32(), 0x61cf9980);
     ///
     /// # Ok::<_, units::parse::UnprefixedHexError>(())
@@ -129,11 +129,11 @@ impl LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// # use bitcoin_primitives::absolute::LockTime;
+    /// # use bitcoin_primitives::absolute;
     ///
     /// // `from_consensus` roundtrips as expected with `to_consensus_u32`.
     /// let n_lock_time: u32 = 741521;
-    /// let lock_time = LockTime::from_consensus(n_lock_time);
+    /// let lock_time = absolute::LockTime::from_consensus(n_lock_time);
     /// assert_eq!(lock_time.to_consensus_u32(), n_lock_time);
     #[inline]
     pub fn from_consensus(n: u32) -> Self {
@@ -157,9 +157,9 @@ impl LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// # use bitcoin_primitives::absolute::LockTime;
-    /// assert!(LockTime::from_height(741521).is_ok());
-    /// assert!(LockTime::from_height(1653195600).is_err());
+    /// # use bitcoin_primitives::absolute;
+    /// assert!(absolute::LockTime::from_height(741521).is_ok());
+    /// assert!(absolute::LockTime::from_height(1653195600).is_err());
     /// ```
     #[inline]
     pub fn from_height(n: u32) -> Result<Self, ConversionError> {
@@ -183,9 +183,9 @@ impl LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// # use bitcoin_primitives::absolute::LockTime;
-    /// assert!(LockTime::from_time(1653195600).is_ok());
-    /// assert!(LockTime::from_time(741521).is_err());
+    /// # use bitcoin_primitives::absolute;
+    /// assert!(absolute::LockTime::from_time(1653195600).is_ok());
+    /// assert!(absolute::LockTime::from_time(741521).is_err());
     /// ```
     #[inline]
     pub fn from_time(n: u32) -> Result<Self, ConversionError> {
@@ -223,12 +223,12 @@ impl LockTime {
     /// # Examples
     ///
     /// ```no_run
-    /// # use bitcoin_primitives::absolute::{LockTime, Height, Time};
+    /// # use bitcoin_primitives::absolute;
     /// // Can be implemented if block chain data is available.
-    /// fn get_height() -> Height { todo!("return the current block height") }
-    /// fn get_time() -> Time { todo!("return the current block time") }
+    /// fn get_height() -> absolute::Height { todo!("return the current block height") }
+    /// fn get_time() -> absolute::Time { todo!("return the current block time") }
     ///
-    /// let n = LockTime::from_consensus(741521); // `n OP_CHEKCLOCKTIMEVERIFY`.
+    /// let n = absolute::LockTime::from_consensus(741521); // `n OP_CHEKCLOCKTIMEVERIFY`.
     /// if n.is_satisfied_by(get_height(), get_time()) {
     ///     // Can create and mine a transaction that satisfies the OP_CLTV timelock constraint.
     /// }
@@ -257,9 +257,9 @@ impl LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// # use bitcoin_primitives::absolute::LockTime;
-    /// let lock_time = LockTime::from_consensus(741521);
-    /// let check = LockTime::from_consensus(741521 + 1);
+    /// # use bitcoin_primitives::absolute;
+    /// let lock_time = absolute::LockTime::from_consensus(741521);
+    /// let check = absolute::LockTime::from_consensus(741521 + 1);
     /// assert!(lock_time.is_implied_by(check));
     /// ```
     #[inline]
@@ -285,9 +285,9 @@ impl LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// # use bitcoin_primitives::absolute::{LockTime, LockTime::*};
-    /// # let n = LockTime::from_consensus(741521);              // n OP_CHECKLOCKTIMEVERIFY
-    /// # let lock_time = LockTime::from_consensus(741521 + 1);  // nLockTime
+    /// # use bitcoin_primitives::absolute::{self, LockTime::*};
+    /// # let n = absolute::LockTime::from_consensus(741521);  // n OP_CHECKLOCKTIMEVERIFY
+    /// # let lock_time = absolute::LockTime::from_consensus(741521 + 1);  // nLockTime
     ///
     /// let _is_satisfied = match (n, lock_time) {
     ///     (Blocks(n), Blocks(lock_time)) => n <= lock_time,
diff --git a/primitives/src/locktime/relative.rs b/primitives/src/locktime/relative.rs
index 85aeeaeaa9..0874225b22 100644
--- a/primitives/src/locktime/relative.rs
+++ b/primitives/src/locktime/relative.rs
@@ -36,16 +36,16 @@ pub use units::locktime::relative::{Height, Time, TimeOverflowError};
 /// # Examples
 ///
 /// ```
-/// use bitcoin_primitives::relative::{LockTime, Height, Time};
-/// let lock_by_height = LockTime::from_height(144); // 144 blocks, approx 24h.
+/// use bitcoin_primitives::relative;
+/// let lock_by_height = relative::LockTime::from_height(144); // 144 blocks, approx 24h.
 /// assert!(lock_by_height.is_block_height());
 ///
-/// let lock_by_time = LockTime::from_512_second_intervals(168); // 168 time intervals, approx 24h.
+/// let lock_by_time = relative::LockTime::from_512_second_intervals(168); // 168 time intervals, approx 24h.
 /// assert!(lock_by_time.is_block_time());
 ///
 /// // Check if a lock time is satisfied by a given height or time.
-/// let height = Height::from(150);
-/// let time = Time::from_512_second_intervals(200);
+/// let height = relative::Height::from(150);
+/// let time = relative::Time::from_512_second_intervals(200);
 /// assert!(lock_by_height.is_satisfied_by(height, time));
 /// assert!(lock_by_time.is_satisfied_by(height, time));
 /// ```
@@ -75,17 +75,17 @@ impl LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// # use bitcoin_primitives::relative::LockTime;
+    /// # use bitcoin_primitives::relative;
     ///
     /// // Values with bit 22 set to 0 will be interpreted as height-based lock times.
     /// let height: u32 = 144; // 144 blocks, approx 24h.
-    /// let lock_time = LockTime::from_consensus(height)?;
+    /// let lock_time = relative::LockTime::from_consensus(height)?;
     /// assert!(lock_time.is_block_height());
     /// assert_eq!(lock_time.to_consensus_u32(), height);
     ///
     /// // Values with bit 22 set to 1 will be interpreted as time-based lock times.
     /// let time: u32 = 168 | (1 << 22) ; // Bit 22 is 1 with time approx 24h.
-    /// let lock_time = LockTime::from_consensus(time)?;
+    /// let lock_time = relative::LockTime::from_consensus(time)?;
     /// assert!(lock_time.is_block_time());
     /// assert_eq!(lock_time.to_consensus_u32(), time);
     ///
@@ -118,11 +118,11 @@ impl LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// # use bitcoin_primitives::{Sequence, relative::LockTime};
+    /// # use bitcoin_primitives::{Sequence, relative};
     ///
     /// // Interpret a sequence number from a Bitcoin transaction input as a relative lock time
     /// let sequence_number = Sequence::from_consensus(144); // 144 blocks, approx 24h.
-    /// let lock_time = LockTime::from_sequence(sequence_number)?;
+    /// let lock_time = relative::LockTime::from_sequence(sequence_number)?;
     /// assert!(lock_time.is_block_height());
     ///
     /// # Ok::<_, bitcoin_primitives::relative::DisabledLockTimeError>(())
@@ -200,12 +200,12 @@ impl LockTime {
     ///
     /// ```rust
     /// # use bitcoin_primitives::Sequence;
-    /// # use bitcoin_primitives::locktime::relative::{Height, Time};
+    /// # use bitcoin_primitives::relative;
     ///
     /// # let required_height = 100;       // 100 blocks.
     /// # let intervals = 70;     // Approx 10 hours.
-    /// # let current_height = || Height::from(required_height + 10);
-    /// # let current_time = || Time::from_512_second_intervals(intervals + 10);
+    /// # let current_height = || relative::Height::from(required_height + 10);
+    /// # let current_time = || relative::Time::from_512_second_intervals(intervals + 10);
     /// # let lock = Sequence::from_height(required_height).to_relative_lock_time().expect("valid height");
     ///
     /// // Users that have chain data can get the current height and time to check against a lock.
@@ -269,10 +269,10 @@ impl LockTime {
     /// # Examples
     ///
     /// ```
-    /// # use bitcoin_primitives::{Sequence, relative::LockTime};
+    /// # use bitcoin_primitives::{Sequence, relative};
     ///
     /// let sequence = Sequence::from_consensus(1 << 22 | 168); // Bit 22 is 1 with time approx 24h.
-    /// let lock_time = LockTime::from_sequence(sequence)?;
+    /// let lock_time = relative::LockTime::from_sequence(sequence)?;
     /// let input_sequence = Sequence::from_consensus(1 << 22 | 336); // Approx 48h.
     /// assert!(lock_time.is_block_time());
     ///
@@ -299,11 +299,11 @@ impl LockTime {
     ///
     /// ```rust
     /// # use bitcoin_primitives::Sequence;
-    /// # use bitcoin_primitives::locktime::relative::Height;
+    /// # use bitcoin_primitives::relative;
     ///
     /// let required_height: u16 = 100;
     /// let lock = Sequence::from_height(required_height).to_relative_lock_time().expect("valid height");
-    /// assert!(lock.is_satisfied_by_height(Height::from(required_height + 1)).expect("a height"));
+    /// assert!(lock.is_satisfied_by_height(relative::Height::from(required_height + 1)).expect("a height"));
     /// ```
     #[inline]
     pub fn is_satisfied_by_height(&self, height: Height) -> Result<bool, IncompatibleHeightError> {
@@ -325,11 +325,11 @@ impl LockTime {
     ///
     /// ```rust
     /// # use bitcoin_primitives::Sequence;
-    /// # use bitcoin_primitives::locktime::relative::Time;
+    /// # use bitcoin_primitives::relative;
     ///
     /// let intervals: u16 = 70; // approx 10 hours;
     /// let lock = Sequence::from_512_second_intervals(intervals).to_relative_lock_time().expect("valid time");
-    /// assert!(lock.is_satisfied_by_time(Time::from_512_second_intervals(intervals + 10)).expect("a time"));
+    /// assert!(lock.is_satisfied_by_time(relative::Time::from_512_second_intervals(intervals + 10)).expect("a time"));
     /// ```
     #[inline]
     pub fn is_satisfied_by_time(&self, time: Time) -> Result<bool, IncompatibleTimeError> {


Test patch: