From 33774122e0f47d5a60acfa057d6e00b7949b1fab Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 31 Oct 2023 15:15:51 +1100 Subject: [PATCH 1/2] Remove public re-exports from private module The `crypto::taproot` module is private, public re-exports are inaccessible, remove them. --- bitcoin/src/crypto/taproot.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/bitcoin/src/crypto/taproot.rs b/bitcoin/src/crypto/taproot.rs index f1c18b2f..d7cc880a 100644 --- a/bitcoin/src/crypto/taproot.rs +++ b/bitcoin/src/crypto/taproot.rs @@ -8,7 +8,6 @@ use core::fmt; use internals::write_err; -pub use secp256k1::{self, constants, Keypair, Parity, Secp256k1, Verification, XOnlyPublicKey}; use crate::prelude::*; use crate::sighash::{InvalidSighashTypeError, TapSighashType}; From 7d695f6b4132f3fcdcd0a1314d8e63e897ba59ee Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Tue, 10 Oct 2023 15:08:50 +1100 Subject: [PATCH 2/2] Improve public re-exports Improve the public exports in two ways: 1. Inline re-exports into the docs of the module that re-exports them. 2. Separate public and private use statements Recently we discussed a way to separate the public and private import statements to make the code more clear and prevent `rustfmt` joining them all together. Separate public exports using a code block and `#[rustfmt::skip]`. Has the nice advantage of reducing the number of `#[doc(inline)]` attributes also. 1. Modules first, as they are part of the project's structure. 2. Private imports 3. Public re-exports (using `rustfmt::skip` to prevent merge) Use the format ```rust mod xyz; mod abc; use ...; pub use { ..., }; ``` This patch introduces changes to the rendered HTML docs. --- bitcoin/src/address/error.rs | 2 + bitcoin/src/address/mod.rs | 10 ++-- bitcoin/src/blockdata/block.rs | 7 ++- bitcoin/src/blockdata/mod.rs | 8 ++- bitcoin/src/blockdata/script/mod.rs | 34 +++++++------ bitcoin/src/blockdata/script/push_bytes.rs | 6 ++- bitcoin/src/blockdata/transaction.rs | 7 ++- bitcoin/src/consensus/mod.rs | 15 +++--- bitcoin/src/crypto/key.rs | 9 ++-- bitcoin/src/error.rs | 2 + bitcoin/src/hash_types.rs | 3 ++ bitcoin/src/lib.rs | 58 +++++++++++----------- bitcoin/src/merkle_tree/mod.rs | 5 +- bitcoin/src/p2p/mod.rs | 7 ++- bitcoin/src/psbt/map/mod.rs | 16 +++--- bitcoin/src/psbt/mod.rs | 23 +++++---- bitcoin/src/sign_message.rs | 5 +- bitcoin/src/taproot.rs | 7 ++- 18 files changed, 138 insertions(+), 86 deletions(-) diff --git a/bitcoin/src/address/error.rs b/bitcoin/src/address/error.rs index 964edb21..7e01868e 100644 --- a/bitcoin/src/address/error.rs +++ b/bitcoin/src/address/error.rs @@ -1,3 +1,5 @@ +//! Error code for the address module. + use core::fmt; use internals::write_err; diff --git a/bitcoin/src/address/mod.rs b/bitcoin/src/address/mod.rs index 1152338e..1b6af53d 100644 --- a/bitcoin/src/address/mod.rs +++ b/bitcoin/src/address/mod.rs @@ -26,6 +26,8 @@ //! bitcoin = { version = "...", features = ["rand-std"] } //! ``` +pub mod error; + use core::convert::{TryFrom, TryInto}; use core::fmt; use core::marker::PhantomData; @@ -49,9 +51,11 @@ use crate::prelude::*; use crate::script::PushBytesBuf; use crate::taproot::TapNodeHash; -/// Error code for the address module. -pub mod error; -pub use self::error::{Error, ParseError, UnknownAddressTypeError}; +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use self::{ + error::{Error, ParseError, UnknownAddressTypeError}, +}; /// The different types of addresses. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] diff --git a/bitcoin/src/blockdata/block.rs b/bitcoin/src/blockdata/block.rs index b08bc5c7..07002105 100644 --- a/bitcoin/src/blockdata/block.rs +++ b/bitcoin/src/blockdata/block.rs @@ -16,13 +16,18 @@ use super::Weight; use crate::blockdata::script; use crate::blockdata::transaction::Transaction; use crate::consensus::{encode, Decodable, Encodable}; -pub use crate::hash_types::BlockHash; use crate::hash_types::{TxMerkleNode, WitnessCommitment, WitnessMerkleNode, Wtxid}; use crate::internal_macros::impl_consensus_encoding; use crate::pow::{CompactTarget, Target, Work}; use crate::prelude::*; use crate::{io, merkle_tree, VarInt}; +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use crate::{ + hash_types::BlockHash, +}; + /// Bitcoin block header. /// /// Contains all the block's information except the actual transactions, but diff --git a/bitcoin/src/blockdata/mod.rs b/bitcoin/src/blockdata/mod.rs index 234f1623..943de54a 100644 --- a/bitcoin/src/blockdata/mod.rs +++ b/bitcoin/src/blockdata/mod.rs @@ -16,5 +16,9 @@ pub mod transaction; pub mod weight; pub mod witness; -pub use fee_rate::FeeRate; -pub use weight::Weight; +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use self::{ + fee_rate::FeeRate, + weight::Weight +}; diff --git a/bitcoin/src/blockdata/script/mod.rs b/bitcoin/src/blockdata/script/mod.rs index 489bc716..413f06cc 100644 --- a/bitcoin/src/blockdata/script/mod.rs +++ b/bitcoin/src/blockdata/script/mod.rs @@ -47,6 +47,16 @@ //! At the time of writing there's only one operation using the cache - `push_verify`, so the cache //! is minimal but we may extend it in the future if needed. +mod borrowed; +mod builder; +mod instruction; +mod owned; +mod push_bytes; +#[cfg(test)] +mod tests; +pub mod witness_program; +pub mod witness_version; + use alloc::rc::Rc; #[cfg(any(not(rust_v_1_60), target_has_atomic = "ptr"))] use alloc::sync::Arc; @@ -65,21 +75,15 @@ use crate::consensus::{encode, Decodable, Encodable}; use crate::prelude::*; use crate::{io, OutPoint}; -mod borrowed; -mod builder; -mod instruction; -mod owned; -mod push_bytes; -#[cfg(test)] -mod tests; -pub mod witness_program; -pub mod witness_version; - -pub use self::borrowed::*; -pub use self::builder::*; -pub use self::instruction::*; -pub use self::owned::*; -pub use self::push_bytes::*; +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use self::{ + borrowed::*, + builder::*, + instruction::*, + owned::*, + push_bytes::*, +}; hashes::hash_newtype! { /// A hash of Bitcoin Script bytecode. diff --git a/bitcoin/src/blockdata/script/push_bytes.rs b/bitcoin/src/blockdata/script/push_bytes.rs index 07cd6f28..3baec542 100644 --- a/bitcoin/src/blockdata/script/push_bytes.rs +++ b/bitcoin/src/blockdata/script/push_bytes.rs @@ -5,11 +5,13 @@ use core::borrow::{Borrow, BorrowMut}; use core::ops::{Deref, DerefMut}; -pub use primitive::*; - #[allow(unused)] use crate::prelude::*; +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use self::primitive::*; + /// This module only contains required operations so that outside functions wouldn't accidentally /// break invariants. Therefore auditing this module should be sufficient. mod primitive { diff --git a/bitcoin/src/blockdata/transaction.rs b/bitcoin/src/blockdata/transaction.rs index 6e38d250..19ad0575 100644 --- a/bitcoin/src/blockdata/transaction.rs +++ b/bitcoin/src/blockdata/transaction.rs @@ -23,8 +23,6 @@ use crate::blockdata::locktime::absolute::{self, Height, Time}; use crate::blockdata::locktime::relative; use crate::blockdata::script::{Script, ScriptBuf}; use crate::blockdata::witness::Witness; -#[cfg(feature = "bitcoinconsensus")] -pub use crate::consensus::validation::TxVerifyError; use crate::consensus::{encode, Decodable, Encodable}; use crate::hash_types::{Txid, Wtxid}; use crate::internal_macros::impl_consensus_encoding; @@ -36,6 +34,11 @@ use crate::sighash::{EcdsaSighashType, TapSighashType}; use crate::string::FromHexStr; use crate::{io, Amount, VarInt}; +#[rustfmt::skip] // Keep public re-exports separate. +#[cfg(feature = "bitcoinconsensus")] +#[doc(inline)] +pub use crate::consensus::validation::TxVerifyError; + /// The marker MUST be a 1-byte zero value: 0x00. (BIP-141) const SEGWIT_MARKER: u8 = 0x00; /// The flag MUST be a 1-byte non-zero value. Currently, 0x01 MUST be used. (BIP-141) diff --git a/bitcoin/src/consensus/mod.rs b/bitcoin/src/consensus/mod.rs index 454ac924..1155a612 100644 --- a/bitcoin/src/consensus/mod.rs +++ b/bitcoin/src/consensus/mod.rs @@ -8,17 +8,20 @@ pub mod encode; pub mod params; +#[cfg(feature = "serde")] +pub mod serde; #[cfg(feature = "bitcoinconsensus")] pub mod validation; -pub use self::encode::{ - deserialize, deserialize_partial, serialize, Decodable, Encodable, ReadExt, WriteExt, +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use self::{ + encode::{deserialize, deserialize_partial, serialize, Decodable, Encodable, ReadExt, WriteExt}, + params::Params, }; -pub use self::params::Params; + #[cfg(feature = "bitcoinconsensus")] +#[doc(inline)] pub use self::validation::{ verify_script, verify_script_with_flags, verify_transaction, verify_transaction_with_flags, }; - -#[cfg(feature = "serde")] -pub mod serde; diff --git a/bitcoin/src/crypto/key.rs b/bitcoin/src/crypto/key.rs index b6321abe..9065add3 100644 --- a/bitcoin/src/crypto/key.rs +++ b/bitcoin/src/crypto/key.rs @@ -12,9 +12,6 @@ use core::str::FromStr; use hashes::{hash160, Hash}; use hex::FromHex; use internals::write_err; -#[cfg(feature = "rand-std")] -pub use secp256k1::rand; -pub use secp256k1::{self, constants, Keypair, Parity, Secp256k1, Verification, XOnlyPublicKey}; use crate::crypto::ecdsa; use crate::network::Network; @@ -22,6 +19,12 @@ use crate::prelude::*; use crate::taproot::{TapNodeHash, TapTweakHash}; use crate::{base58, io}; +#[rustfmt::skip] // Keep public re-exports separate. +pub use secp256k1::{self, constants, Keypair, Parity, Secp256k1, Verification, XOnlyPublicKey}; + +#[cfg(feature = "rand-std")] +pub use secp256k1::rand; + /// A Bitcoin ECDSA public key #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct PublicKey { diff --git a/bitcoin/src/error.rs b/bitcoin/src/error.rs index f5ea45c3..6adcbbb0 100644 --- a/bitcoin/src/error.rs +++ b/bitcoin/src/error.rs @@ -2,4 +2,6 @@ //! Contains error types and other error handling tools. +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] pub use crate::parse::ParseIntError; diff --git a/bitcoin/src/hash_types.rs b/bitcoin/src/hash_types.rs index ccbc4faa..3ac56a74 100644 --- a/bitcoin/src/hash_types.rs +++ b/bitcoin/src/hash_types.rs @@ -47,7 +47,10 @@ macro_rules! impl_asref_push_bytes { }; } pub(crate) use impl_asref_push_bytes; + // newtypes module is solely here so we can rustfmt::skip. +#[rustfmt::skip] +#[doc(inline)] pub use newtypes::*; #[rustfmt::skip] diff --git a/bitcoin/src/lib.rs b/bitcoin/src/lib.rs index 68b7d246..bb9fda40 100644 --- a/bitcoin/src/lib.rs +++ b/bitcoin/src/lib.rs @@ -129,36 +129,34 @@ use core2::error::Error as StdError; #[cfg(not(feature = "std"))] use core2::io; -pub use crate::address::{Address, AddressType}; -pub use crate::amount::{Amount, Denomination, SignedAmount}; -pub use crate::bip32::XKeyIdentifier; -pub use crate::blockdata::block::{self, Block}; -pub use crate::blockdata::constants; -pub use crate::blockdata::fee_rate::FeeRate; -pub use crate::blockdata::locktime::{self, absolute, relative}; -pub use crate::blockdata::opcodes::{self, Opcode}; -pub use crate::blockdata::script::witness_program::{self, WitnessProgram}; -pub use crate::blockdata::script::witness_version::{self, WitnessVersion}; -pub use crate::blockdata::script::{self, Script, ScriptBuf, ScriptHash, WScriptHash}; -pub use crate::blockdata::transaction::{self, OutPoint, Sequence, Transaction, TxIn, TxOut}; -pub use crate::blockdata::weight::Weight; -pub use crate::blockdata::witness::{self, Witness}; -pub use crate::consensus::encode::VarInt; -pub use crate::crypto::ecdsa; -pub use crate::crypto::key::{ - self, PrivateKey, PubkeyHash, PublicKey, WPubkeyHash, XOnlyPublicKey, -}; -pub use crate::crypto::sighash::{self, LegacySighash, SegwitV0Sighash, TapSighash, TapSighashTag}; -pub use crate::hash_types::{ - BlockHash, FilterHash, FilterHeader, TxMerkleNode, Txid, WitnessCommitment, Wtxid, -}; -pub use crate::merkle_tree::MerkleBlock; -pub use crate::network::Network; -pub use crate::pow::{CompactTarget, Target, Work}; -pub use crate::psbt::Psbt; -pub use crate::sighash::{EcdsaSighashType, TapSighashType}; -pub use crate::taproot::{ - TapBranchTag, TapLeafHash, TapLeafTag, TapNodeHash, TapTweakHash, TapTweakTag, +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use crate::{ + address::{Address, AddressType}, + amount::{Amount, Denomination, SignedAmount}, + bip32::XKeyIdentifier, + blockdata::block::{self, Block}, + blockdata::constants, + blockdata::fee_rate::FeeRate, + blockdata::locktime::{self, absolute, relative}, + blockdata::opcodes::{self, Opcode}, + blockdata::script::witness_program::{self, WitnessProgram}, + blockdata::script::witness_version::{self, WitnessVersion}, + blockdata::script::{self, Script, ScriptBuf, ScriptHash, WScriptHash}, + blockdata::transaction::{self, OutPoint, Sequence, Transaction, TxIn, TxOut}, + blockdata::weight::Weight, + blockdata::witness::{self, Witness}, + consensus::encode::VarInt, + crypto::ecdsa, + crypto::key::{self, PrivateKey, PubkeyHash, PublicKey, WPubkeyHash, XOnlyPublicKey}, + crypto::sighash::{self, LegacySighash, SegwitV0Sighash, TapSighash, TapSighashTag}, + hash_types::{BlockHash, FilterHash, FilterHeader, TxMerkleNode, Txid, WitnessCommitment, Wtxid}, + merkle_tree::MerkleBlock, + network::Network, + pow::{CompactTarget, Target, Work}, + psbt::Psbt, + sighash::{EcdsaSighashType, TapSighashType}, + taproot::{TapBranchTag, TapLeafHash, TapLeafTag, TapNodeHash, TapTweakHash, TapTweakTag}, }; #[cfg(not(feature = "std"))] diff --git a/bitcoin/src/merkle_tree/mod.rs b/bitcoin/src/merkle_tree/mod.rs index c120d8fa..7d75641f 100644 --- a/bitcoin/src/merkle_tree/mod.rs +++ b/bitcoin/src/merkle_tree/mod.rs @@ -18,13 +18,16 @@ mod block; use core::cmp::min; use core::iter; -pub use block::{MerkleBlock, MerkleBlockError, PartialMerkleTree}; use hashes::Hash; use crate::consensus::encode::Encodable; use crate::io; use crate::prelude::*; +#[rustfmt::skip] +#[doc(inline)] +pub use self::block::{MerkleBlock, MerkleBlockError, PartialMerkleTree}; + /// Calculates the merkle root of a list of *hashes*, inline (in place) in `hashes`. /// /// In most cases, you'll want to use [`calculate_root`] instead. Please note, calling this function diff --git a/bitcoin/src/p2p/mod.rs b/bitcoin/src/p2p/mod.rs index c7f67570..3132c025 100644 --- a/bitcoin/src/p2p/mod.rs +++ b/bitcoin/src/p2p/mod.rs @@ -8,8 +8,6 @@ #[cfg(feature = "std")] pub mod address; #[cfg(feature = "std")] -pub use self::address::Address; -#[cfg(feature = "std")] pub mod message; #[cfg(feature = "std")] pub mod message_blockdata; @@ -33,6 +31,11 @@ use crate::consensus::encode::{self, Decodable, Encodable}; use crate::prelude::{Borrow, BorrowMut, String, ToOwned}; use crate::{io, Network}; +#[rustfmt::skip] +#[doc(inline)] +#[cfg(feature = "std")] +pub use self::address::Address; + /// Version of the protocol as appearing in network message headers. /// /// This constant is used to signal to other peers which features you support. Increasing it implies diff --git a/bitcoin/src/psbt/map/mod.rs b/bitcoin/src/psbt/map/mod.rs index 91d455e0..f416e5db 100644 --- a/bitcoin/src/psbt/map/mod.rs +++ b/bitcoin/src/psbt/map/mod.rs @@ -1,15 +1,19 @@ // SPDX-License-Identifier: CC0-1.0 -use crate::prelude::*; -use crate::psbt::raw; - mod global; mod input; mod output; -pub use self::input::{Input, PsbtSighashType}; -pub use self::output::Output; -use super::serialize::Serialize; +use crate::prelude::*; +use crate::psbt::raw; +use crate::psbt::serialize::Serialize; + +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use self::{ + input::{Input, PsbtSighashType}, + output::Output, +}; /// A trait that describes a PSBT key-value map. pub(super) trait Map { diff --git a/bitcoin/src/psbt/mod.rs b/bitcoin/src/psbt/mod.rs index a44daa6f..925ea413 100644 --- a/bitcoin/src/psbt/mod.rs +++ b/bitcoin/src/psbt/mod.rs @@ -7,6 +7,13 @@ //! except we define PSBTs containing non-standard sighash types as invalid. //! +#[macro_use] +mod macros; +mod error; +mod map; +pub mod raw; +pub mod serialize; + use core::{cmp, fmt}; #[cfg(feature = "std")] use std::collections::{HashMap, HashSet}; @@ -23,16 +30,12 @@ use crate::prelude::*; use crate::sighash::{self, EcdsaSighashType, SighashCache}; use crate::{Amount, FeeRate}; -#[macro_use] -mod macros; -pub mod raw; -pub mod serialize; - -mod error; -pub use self::error::Error; - -mod map; -pub use self::map::{Input, Output, PsbtSighashType}; +#[rustfmt::skip] // Keep public re-exports separate. +#[doc(inline)] +pub use self::{ + map::{Input, Output, PsbtSighashType}, + error::Error, +}; /// A Partially Signed Transaction. #[derive(Debug, Clone, PartialEq, Eq, Hash)] diff --git a/bitcoin/src/sign_message.rs b/bitcoin/src/sign_message.rs index 17a00ec2..d846946a 100644 --- a/bitcoin/src/sign_message.rs +++ b/bitcoin/src/sign_message.rs @@ -8,9 +8,12 @@ use hashes::{sha256d, Hash, HashEngine}; +use crate::consensus::{encode, Encodable}; + +#[rustfmt::skip] +#[doc(inline)] #[cfg(feature = "secp-recovery")] pub use self::message_signing::{MessageSignature, MessageSignatureError}; -use crate::consensus::{encode, Encodable}; /// The prefix for signed messages using Bitcoin's message signing protocol. pub const BITCOIN_SIGNED_MSG_PREFIX: &[u8] = b"\x18Bitcoin Signed Message:\n"; diff --git a/bitcoin/src/taproot.rs b/bitcoin/src/taproot.rs index 9c5ccc9f..8b1e80d8 100644 --- a/bitcoin/src/taproot.rs +++ b/bitcoin/src/taproot.rs @@ -16,11 +16,14 @@ use secp256k1::{self, Scalar, Secp256k1}; use crate::consensus::Encodable; use crate::crypto::key::{TapTweak, TweakedPublicKey, UntweakedPublicKey, XOnlyPublicKey}; -// Re-export these so downstream only has to use one `taproot` module. -pub use crate::crypto::taproot::{SigFromSliceError, Signature}; use crate::prelude::*; use crate::{io, Script, ScriptBuf}; +// Re-export these so downstream only has to use one `taproot` module. +#[rustfmt::skip] +#[doc(inline)] +pub use crate::crypto::taproot::{SigFromSliceError, Signature}; + // Taproot test vectors from BIP-341 state the hashes without any reversing sha256t_hash_newtype! { pub struct TapLeafTag = hash_str("TapLeaf");