From e58cda6f92b8855d6bed1ebed76bdbf8030367a0 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Mon, 16 Sep 2024 09:58:15 +0100 Subject: [PATCH 1/4] Remove `unused_imports` in docs Examples in documentation are not linted in the same way as other code, but should still contain correctly written code. unused_imports in docs have been removed in bitcoin, and a warn attribute added to lib.rs. --- bitcoin/src/address/mod.rs | 4 ---- bitcoin/src/bip32.rs | 1 - bitcoin/src/blockdata/transaction.rs | 2 +- bitcoin/src/crypto/sighash.rs | 4 ++-- bitcoin/src/lib.rs | 1 + bitcoin/src/merkle_tree/block.rs | 3 +-- 6 files changed, 5 insertions(+), 10 deletions(-) diff --git a/bitcoin/src/address/mod.rs b/bitcoin/src/address/mod.rs index c944c6252..38c171b37 100644 --- a/bitcoin/src/address/mod.rs +++ b/bitcoin/src/address/mod.rs @@ -307,7 +307,6 @@ pub enum AddressData { /// 1. `Display` is implemented only for `Address`: /// /// ``` -/// # use std::str::FromStr; /// # use bitcoin::address::{Address, NetworkChecked}; /// let address: Address = "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM".parse::>() /// .unwrap().assume_checked(); @@ -315,7 +314,6 @@ pub enum AddressData { /// ``` /// /// ```ignore -/// # use std::str::FromStr; /// # use bitcoin::address::{Address, NetworkChecked}; /// let address: Address = "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM".parse::>() /// .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 = "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM".parse::>() /// .unwrap(); @@ -335,7 +332,6 @@ pub enum AddressData { /// ``` /// /// ``` -/// # use std::str::FromStr; /// # use bitcoin::address::{Address, NetworkChecked}; /// let address: Address = "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM".parse::>() /// .unwrap().assume_checked(); diff --git a/bitcoin/src/bip32.rs b/bitcoin/src/bip32.rs index cf7dc4520..55ad3ae80 100644 --- a/bitcoin/src/bip32.rs +++ b/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::().unwrap(); /// const HARDENED: u32 = 0x80000000; diff --git a/bitcoin/src/blockdata/transaction.rs b/bitcoin/src/blockdata/transaction.rs index 174afff09..cfdf0a5d2 100644 --- a/bitcoin/src/blockdata/transaction.rs +++ b/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(¶ms::MAINNET); /// let tx = &block.txdata[0]; diff --git a/bitcoin/src/crypto/sighash.rs b/bitcoin/src/crypto/sighash.rs index 0e17f7b32..77ed7aa6f 100644 --- a/bitcoin/src/crypto/sighash.rs +++ b/bitcoin/src/crypto/sighash.rs @@ -1370,8 +1370,8 @@ impl EncodeSigningDataResult { /// /// ```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; diff --git a/bitcoin/src/lib.rs b/bitcoin/src/lib.rs index 8ebd84bce..546c97e95 100644 --- a/bitcoin/src/lib.rs +++ b/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))] diff --git a/bitcoin/src/merkle_tree/block.rs b/bitcoin/src/merkle_tree/block.rs index a29020475..6034dc29c 100644 --- a/bitcoin/src/merkle_tree/block.rs +++ b/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 = [ From ff6b1d4f19d2c34c100ff2c291f5cbb49b4b6bd6 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Mon, 16 Sep 2024 17:11:04 +0100 Subject: [PATCH 2/4] Remove unused variables and methods from docs Examples in documentation are not linted in the same way as other code, but should still contain correctly written code. Throughout the bitcoin crate unused variables have either been prefixed with _ or an assert used. And unused methods have been used in the example code. --- bitcoin/src/address/mod.rs | 6 +++--- bitcoin/src/network/params.rs | 2 ++ bitcoin/src/psbt/map/input.rs | 8 ++++---- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/bitcoin/src/address/mod.rs b/bitcoin/src/address/mod.rs index 38c171b37..7aa72868e 100644 --- a/bitcoin/src/address/mod.rs +++ b/bitcoin/src/address/mod.rs @@ -288,14 +288,14 @@ pub enum AddressData { /// /// // variant 1 /// let address: Address = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse().unwrap(); -/// let address: Address = address.require_network(Network::Bitcoin).unwrap(); +/// let _address: Address = 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 = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse::>() +/// let _address: Address = "32iVBEu4dxkUQk9dJbZUiBiQdmypcEyJRf".parse::>() /// .unwrap().require_network(Network::Bitcoin).unwrap(); /// ``` /// diff --git a/bitcoin/src/network/params.rs b/bitcoin/src/network/params.rs index 9d9cc5f56..ca93169c6 100644 --- a/bitcoin/src/network/params.rs +++ b/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); //! # } //! ``` diff --git a/bitcoin/src/psbt/map/input.rs b/bitcoin/src/psbt/map/input.rs index e9502daf1..803780d23 100644 --- a/bitcoin/src/psbt/map/input.rs +++ b/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 }; From fd89ddf4012c4dbfce07450b868dfdbcb0d6b2e6 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Tue, 17 Sep 2024 16:25:43 +0100 Subject: [PATCH 3/4] Remove or fix unused variables and methods in docs Examples in documentation are not linted in the same way as other code, but should still contain correctly written code. Throughout all of the crates except internals (another commit) unused variables have been prefixed with `_`, unused imports have been removed, and a warn attribute added to all of the `lib.rs` files. --- addresses/src/lib.rs | 1 + base58/src/lib.rs | 1 + hashes/src/lib.rs | 10 +++------- io/src/lib.rs | 1 + primitives/src/lib.rs | 1 + primitives/src/locktime/absolute.rs | 7 +++---- primitives/src/locktime/relative.rs | 7 +++---- units/src/lib.rs | 1 + 8 files changed, 14 insertions(+), 15 deletions(-) diff --git a/addresses/src/lib.rs b/addresses/src/lib.rs index 32b7bda62..18604ce0a 100644 --- a/addresses/src/lib.rs +++ b/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. diff --git a/base58/src/lib.rs b/base58/src/lib.rs index 3677bd2d8..1c7e04a2d 100644 --- a/base58/src/lib.rs +++ b/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))] diff --git a/hashes/src/lib.rs b/hashes/src/lib.rs index b332b9a1f..31080d192 100644 --- a/hashes/src/lib.rs +++ b/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))] diff --git a/io/src/lib.rs b/io/src/lib.rs index e3b7ac0cb..387fbdffb 100644 --- a/io/src/lib.rs +++ b/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. diff --git a/primitives/src/lib.rs b/primitives/src/lib.rs index e6743bc1e..83149ba20 100644 --- a/primitives/src/lib.rs +++ b/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. diff --git a/primitives/src/locktime/absolute.rs b/primitives/src/locktime/absolute.rs index 93f31a2c6..b5205524b 100644 --- a/primitives/src/locktime/absolute.rs +++ b/primitives/src/locktime/absolute.rs @@ -46,7 +46,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"), @@ -108,7 +108,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; @@ -237,7 +236,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)); @@ -270,7 +269,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"), diff --git a/primitives/src/locktime/relative.rs b/primitives/src/locktime/relative.rs index a890b940b..0d9658c5e 100644 --- a/primitives/src/locktime/relative.rs +++ b/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"); diff --git a/units/src/lib.rs b/units/src/lib.rs index addedf8d5..af2890b01 100644 --- a/units/src/lib.rs +++ b/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. From f6abdcc001cd0ecddec48e753c2009121036e5f6 Mon Sep 17 00:00:00 2001 From: "Jamil Lambert, PhD" Date: Tue, 17 Sep 2024 16:29:57 +0100 Subject: [PATCH 4/4] Allow unused in `macros.rs` docs The example code in macros.rs is much clearer as it is than changing it to remove the warnings created by adding the warn attribute to the `lib.rs` file. The example code was enclosed within a function block and `#[allow(unused)]` added. And a warn attribute added to `lib.rs`. --- internals/src/lib.rs | 1 + internals/src/macros.rs | 7 +++++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/internals/src/lib.rs b/internals/src/lib.rs index 353234b5d..ff78d9581 100644 --- a/internals/src/lib.rs +++ b/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. diff --git a/internals/src/macros.rs b/internals/src/macros.rs index f51f692d3..d0ae5bbb1 100644 --- a/internals/src/macros.rs +++ b/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 { Item(T) }; +/// enum GammaEnum { Item(T) } /// impl_from_infallible!(GammaEnum); /// /// 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 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]