Merge rust-bitcoin/rust-bitcoin#3364: Remove unused inports, and fix unused variables and methods in docs

f6abdcc001 Allow unused in `macros.rs` docs (Jamil Lambert, PhD)
fd89ddf401 Remove or fix unused variables and methods in docs (Jamil Lambert, PhD)
ff6b1d4f19 Remove unused variables and methods from docs (Jamil Lambert, PhD)
e58cda6f92 Remove `unused_imports` in docs (Jamil Lambert, PhD)

Pull request description:

  As mentioned in #3362 examples in documentation are not linted in the same way as other code, but should still contain correctly written code.

  #![doc(test(attr(warn(unused))))] has been added to all lib.rs files

  In the docs throughout all crates:

  - Unused imports have been removed.

  - Unused variables, structs and enums have been used e.g. with an `assert_eq!` or prefixed with `_`

  - Unused methods have been called in the example code.

ACKs for top commit:
  tcharding:
    ACK f6abdcc001
  apoelstra:
    ACK f6abdcc001 successfully ran local tests

Tree-SHA512: c3de1775ecde6971056e9fed2c9fa1621785787a6a6ccbf3a6dbd11e18d42d4956949f3f8adfc75d94fd25db998b04adb1c346cc2c2ba47f4dc37402e1388277

addresses/src/lib.rs

@@ -14,6 +14,7 @@
 #![cfg_attr(all(not(test), not(feature = "std")), no_std)]
 // Experimental features we need.
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![doc(test(attr(warn(unused))))]
 // Coding conventions.
 #![warn(missing_docs)]
 // Exclude lints we don't think are valuable.

base58/src/lib.rs

@@ -12,6 +12,7 @@
 #![cfg_attr(bench, feature(test))]
 // Coding conventions.
 #![warn(missing_docs)]
+#![doc(test(attr(warn(unused))))]
 // Instead of littering the codebase for non-fuzzing and bench code just globally allow.
 #![cfg_attr(fuzzing, allow(dead_code, unused_imports))]
 #![cfg_attr(bench, allow(dead_code, unused_imports))]

bitcoin/src/address/mod.rs

@@ -288,14 +288,14 @@ pub enum AddressData {
 ///
 /// // variant 1
 /// let address: Address<NetworkUnchecked> = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse().unwrap();
-/// let address: Address<NetworkChecked> = address.require_network(Network::Bitcoin).unwrap();
+/// let _address: Address<NetworkChecked> = address.require_network(Network::Bitcoin).unwrap();
 ///
 /// // variant 2
-/// let address: Address = Address::from_str("32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf").unwrap()
+/// let _address: Address = Address::from_str("32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf").unwrap()
 ///                .require_network(Network::Bitcoin).unwrap();
 ///
 /// // variant 3
-/// let address: Address<NetworkChecked> = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse::<Address<_>>()
+/// let _address: Address<NetworkChecked> = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse::<Address<_>>()
 ///                .unwrap().require_network(Network::Bitcoin).unwrap();
 /// ```
 ///
@@ -307,7 +307,6 @@ pub enum AddressData {
 /// 1. `Display` is implemented only for `Address<NetworkChecked>`:
 ///
 /// ```
-/// # use std::str::FromStr;
 /// # use bitcoin::address::{Address, NetworkChecked};
 /// let address: Address<NetworkChecked> = "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM".parse::<Address<_>>()
 ///                .unwrap().assume_checked();
@@ -315,7 +314,6 @@ pub enum AddressData {
 /// ```
 ///
 /// ```ignore
-/// # use std::str::FromStr;
 /// # use bitcoin::address::{Address, NetworkChecked};
 /// let address: Address<NetworkUnchecked> = "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM".parse::<Address<_>>()
 ///                .unwrap();
@@ -327,7 +325,6 @@ pub enum AddressData {
 ///    check the network and use `Display` in user-facing context.
 ///
 /// ```
-/// # use std::str::FromStr;
 /// # use bitcoin::address::{Address, NetworkUnchecked};
 /// let address: Address<NetworkUnchecked> = "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM".parse::<Address<_>>()
 ///                .unwrap();
@@ -335,7 +332,6 @@ pub enum AddressData {
 /// ```
 ///
 /// ```
-/// # use std::str::FromStr;
 /// # use bitcoin::address::{Address, NetworkChecked};
 /// let address: Address<NetworkChecked> = "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM".parse::<Address<_>>()
 ///                .unwrap().assume_checked();

bitcoin/src/bip32.rs

@@ -444,7 +444,6 @@ impl DerivationPath {
     ///
     /// ```
     /// use bitcoin::bip32::DerivationPath;
-    /// use std::str::FromStr;
     ///
     /// let path = "m/84'/0'/0'/0/1".parse::<DerivationPath>().unwrap();
     /// const HARDENED: u32 = 0x80000000;

bitcoin/src/blockdata/transaction.rs

@@ -114,7 +114,7 @@ impl OutPoint {
     ///
     /// ```rust
     /// use bitcoin::constants::genesis_block;
-    /// use bitcoin::{params, Network};
+    /// use bitcoin::params;
     ///
     /// let block = genesis_block(&params::MAINNET);
     /// let tx = &block.txdata[0];

bitcoin/src/crypto/sighash.rs

@@ -1370,8 +1370,8 @@ impl<E> EncodeSigningDataResult<E> {
     ///
     /// ```rust
     /// # use bitcoin::consensus::deserialize;
-    /// # use bitcoin::hashes::{sha256d, Hash, hex::FromHex};
-    /// # use bitcoin::sighash::{LegacySighash, SighashCache};
+    /// # use bitcoin::hashes::{sha256d, hex::FromHex};
+    /// # use bitcoin::sighash::SighashCache;
     /// # use bitcoin::Transaction;
     /// # let mut writer = sha256d::Hash::engine();
     /// # let input_index = 0;

bitcoin/src/lib.rs

@@ -30,6 +30,7 @@
 #![cfg_attr(bench, feature(test))]
 // Coding conventions.
 #![warn(missing_docs)]
+#![doc(test(attr(warn(unused))))]
 // Instead of littering the codebase for non-fuzzing and bench code just globally allow.
 #![cfg_attr(fuzzing, allow(dead_code, unused_imports))]
 #![cfg_attr(bench, allow(dead_code, unused_imports))]

bitcoin/src/merkle_tree/block.rs

@@ -197,8 +197,7 @@ impl PartialMerkleTree {
     ///
     /// ```rust
     /// use bitcoin::hash_types::Txid;
-    /// use bitcoin::hex::FromHex;
-    /// use bitcoin::merkle_tree::{MerkleBlock, PartialMerkleTree};
+    /// use bitcoin::merkle_tree::PartialMerkleTree;
     ///
     /// // Block 80000
     /// let txids: Vec<Txid> = [

bitcoin/src/network/params.rs

@@ -61,6 +61,8 @@
 //! #    let _ = target.difficulty(signet);
 //! #
 //! #    let custom = CustomParams::new();
+//! #    let _ = custom.magic();
+//! #    let _ = custom.challenge_script();
 //! #    let _ = target.difficulty(custom);
 //! # }
 //! ```

bitcoin/src/psbt/map/input.rs

@@ -144,8 +144,8 @@ pub struct Input {
 /// use bitcoin::{EcdsaSighashType, TapSighashType};
 /// use bitcoin::psbt::PsbtSighashType;
 ///
-/// let ecdsa_sighash_all: PsbtSighashType = EcdsaSighashType::All.into();
-/// let tap_sighash_all: PsbtSighashType = TapSighashType::All.into();
+/// let _ecdsa_sighash_all: PsbtSighashType = EcdsaSighashType::All.into();
+/// let _tap_sighash_all: PsbtSighashType = TapSighashType::All.into();
 /// ```
 #[derive(Copy, Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
@@ -208,8 +208,8 @@ impl PsbtSighashType {
     /// ```
     /// use bitcoin::{EcdsaSighashType, TapSighashType};
     /// use bitcoin::psbt::PsbtSighashType;
-    /// let ecdsa_sighash_anyone_can_pay: PsbtSighashType = EcdsaSighashType::AllPlusAnyoneCanPay.into();
-    /// let tap_sighash_anyone_can_pay: PsbtSighashType = TapSighashType::AllPlusAnyoneCanPay.into();
+    /// let _ecdsa_sighash_anyone_can_pay: PsbtSighashType = EcdsaSighashType::AllPlusAnyoneCanPay.into();
+    /// let _tap_sighash_anyone_can_pay: PsbtSighashType = TapSighashType::AllPlusAnyoneCanPay.into();
     /// ```
     pub const ALL: PsbtSighashType = PsbtSighashType { inner: 0x01 };
 

hashes/src/lib.rs

@@ -15,16 +15,14 @@
 //! use bitcoin_hashes::Sha256;
 //!
 //! let bytes = [0u8; 5];
-//! let hash_of_bytes = Sha256::hash(&bytes);
-//! let hash_of_string = Sha256::hash("some string".as_bytes());
+//! let _hash_of_bytes = Sha256::hash(&bytes);
+//! let _hash_of_string = Sha256::hash("some string".as_bytes());
 //! ```
 //!
 //!
 //! Hashing content from a reader:
 //!
 //! ```rust
-//! use bitcoin_hashes::Sha256;
-//!
 //! #[cfg(std)]
 //! # fn main() -> std::io::Result<()> {
 //! let mut reader: &[u8] = b"hello"; // in real code, this could be a `File` or `TcpStream`
@@ -42,9 +40,6 @@
 //! Hashing content by [`std::io::Write`] on `HashEngine`:
 //!
 //! ```rust
-//! use bitcoin_hashes::Sha256;
-//! use std::io::Write;
-//!
 //! #[cfg(std)]
 //! # fn main() -> std::io::Result<()> {
 //! let mut part1: &[u8] = b"hello";
@@ -68,6 +63,7 @@
 #![cfg_attr(bench, feature(test))]
 // Coding conventions.
 #![warn(missing_docs)]
+#![doc(test(attr(warn(unused))))]
 // Instead of littering the codebase for non-fuzzing and bench code just globally allow.
 #![cfg_attr(hashes_fuzz, allow(dead_code, unused_imports))]
 #![cfg_attr(bench, allow(dead_code, unused_imports))]

internals/src/lib.rs

@@ -10,6 +10,7 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 // Coding conventions.
 #![warn(missing_docs)]
+#![doc(test(attr(warn(unused))))]
 // Exclude lints we don't think are valuable.
 #![allow(clippy::needless_question_mark)] // https://github.com/rust-bitcoin/rust-bitcoin/pull/2134
 #![allow(clippy::manual_range_contains)] // More readable than clippy's format.

internals/src/macros.rs

@@ -158,6 +158,8 @@ macro_rules! const_assert {
 /// # Examples
 ///
 /// ```rust
+/// # #[allow(unused)]
+/// # fn main() {
 /// # use core::fmt::{Display, Debug};
 /// use bitcoin_internals::impl_from_infallible;
 ///
@@ -167,7 +169,7 @@ macro_rules! const_assert {
 /// enum BetaEnum<'b> { Item(&'b usize) }
 /// impl_from_infallible!(BetaEnum<'b>);
 ///
-/// enum GammaEnum<T> { Item(T) };
+/// enum GammaEnum<T> { Item(T) }
 /// impl_from_infallible!(GammaEnum<T>);
 ///
 /// enum DeltaEnum<'b, 'a: 'static + 'b, T: 'a, D: Debug + Display + 'a> {
@@ -189,6 +191,7 @@ macro_rules! const_assert {
 ///     what: &'b D,
 /// }
 /// impl_from_infallible!(DeltaStruct<'b, 'a: 'static + 'b, T: 'a, D: Debug + Display + 'a>);
+/// # }
 /// ```
 ///
 /// See <https://stackoverflow.com/a/61189128> for more information about this macro.
@@ -208,7 +211,7 @@ macro_rules! impl_from_infallible {
 /// Adds an implementation of `pub fn to_hex(&self) -> String` if `alloc` feature is enabled.
 ///
 /// The added function allocates a `String` then calls through to [`core::fmt::LowerHex`].
-/// 
+///
 /// Note: Calling this macro assumes that the calling crate has an `alloc` feature that also activates the
 /// `alloc` crate. Calling this macro without the `alloc` feature enabled is a no-op.
 #[macro_export]

io/src/lib.rs

@@ -13,6 +13,7 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 // Coding conventions.
 #![warn(missing_docs)]
+#![doc(test(attr(warn(unused))))]
 // Exclude lints we don't think are valuable.
 #![allow(clippy::needless_question_mark)] // https://github.com/rust-bitcoin/rust-bitcoin/pull/2134
 #![allow(clippy::manual_range_contains)] // More readable than clippy's format.

primitives/src/lib.rs

@@ -13,6 +13,7 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 // Coding conventions.
 #![warn(missing_docs)]
+#![doc(test(attr(warn(unused))))]
 // Exclude lints we don't think are valuable.
 #![allow(clippy::needless_question_mark)] // https://github.com/rust-bitcoin/rust-bitcoin/pull/2134
 #![allow(clippy::manual_range_contains)] // More readable than clippy's format.

primitives/src/locktime/absolute.rs

@@ -48,7 +48,7 @@ pub use units::locktime::absolute::*;
 /// # let n = LockTime::from_consensus(741521);          // n OP_CHECKLOCKTIMEVERIFY
 /// # let lock_time = 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) {
+/// let _is_satisfied = match (n, lock_time) {
 ///     (Blocks(n), Blocks(lock_time)) => n <= lock_time,
 ///     (Seconds(n), Seconds(lock_time)) => n <= lock_time,
 ///     _ => panic!("handle invalid comparison error"),
@@ -110,7 +110,6 @@ impl LockTime {
     ///
     /// ```rust
     /// # use bitcoin_primitives::absolute::LockTime;
-    /// # let n = LockTime::from_consensus(741521); // n OP_CHECKLOCKTIMEVERIFY
     ///
     /// // `from_consensus` roundtrips as expected with `to_consensus_u32`.
     /// let n_lock_time: u32 = 741521;
@@ -239,7 +238,7 @@ impl LockTime {
     /// # Examples
     ///
     /// ```rust
-    /// # use bitcoin_primitives::absolute::{LockTime, LockTime::*};
+    /// # use bitcoin_primitives::absolute::LockTime;
     /// let lock_time = LockTime::from_consensus(741521);
     /// let check = LockTime::from_consensus(741521 + 1);
     /// assert!(lock_time.is_implied_by(check));
@@ -272,7 +271,7 @@ impl LockTime {
     /// # let n = LockTime::from_consensus(741521);              // n OP_CHECKLOCKTIMEVERIFY
     /// # let lock_time = LockTime::from_consensus(741521 + 1);  // nLockTime
     ///
-    /// let is_satisfied = match (n, lock_time) {
+    /// let _is_satisfied = match (n, lock_time) {
     ///     (Blocks(n), Blocks(lock_time)) => n <= lock_time,
     ///     (Seconds(n), Seconds(lock_time)) => n <= lock_time,
     ///     _ => panic!("invalid comparison"),

primitives/src/locktime/relative.rs

@@ -165,7 +165,7 @@ impl LockTime {
     ///
     /// ```rust
     /// # use bitcoin_primitives::Sequence;
-    /// # use bitcoin_primitives::locktime::relative::{LockTime, Height, Time};
+    /// # use bitcoin_primitives::locktime::relative::{Height, Time};
     ///
     /// # let required_height = 100;       // 100 blocks.
     /// # let intervals = 70;     // Approx 10 hours.
@@ -204,7 +204,6 @@ impl LockTime {
     ///
     /// ```rust
     /// # use bitcoin_primitives::Sequence;
-    /// # use bitcoin_primitives::locktime::relative::{LockTime, Height, Time};
     ///
     /// # let required_height = 100;       // 100 blocks.
     /// # let lock = Sequence::from_height(required_height).to_relative_lock_time().expect("valid height");
@@ -252,7 +251,7 @@ impl LockTime {
     ///
     /// ```rust
     /// # use bitcoin_primitives::Sequence;
-    /// # use bitcoin_primitives::locktime::relative::{LockTime, Height, Time};
+    /// # use bitcoin_primitives::locktime::relative::Height;
     ///
     /// let required_height: u16 = 100;
     /// let lock = Sequence::from_height(required_height).to_relative_lock_time().expect("valid height");
@@ -279,7 +278,7 @@ impl LockTime {
     ///
     /// ```rust
     /// # use bitcoin_primitives::Sequence;
-    /// # use bitcoin_primitives::locktime::relative::{LockTime, Height, Time};
+    /// # use bitcoin_primitives::locktime::relative::Time;
     ///
     /// let intervals: u16 = 70; // approx 10 hours;
     /// let lock = Sequence::from_512_second_intervals(intervals).to_relative_lock_time().expect("valid time");

units/src/lib.rs

@@ -8,6 +8,7 @@
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 // Coding conventions.
 #![warn(missing_docs)]
+#![doc(test(attr(warn(unused))))]
 // Exclude lints we don't think are valuable.
 #![allow(clippy::needless_question_mark)] // https://github.com/rust-bitcoin/rust-bitcoin/pull/2134
 #![allow(clippy::manual_range_contains)] // More readable than clippy's format.