Merge rust-bitcoin/rust-bitcoin#2120: Improve public re-exports

7d695f6b41 Improve public re-exports (Tobin C. Harding)
33774122e0 Remove public re-exports from private module (Tobin C. Harding)

Pull request description:

  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.

ACKs for top commit:
  apoelstra:
    ACK 7d695f6b41

Tree-SHA512: dc9121c0fe282e3035d862beadb89e2d5a374a7dab6b1c3147a9b5960f8bc2f5af49892f0f713f55c645c46f53464c32daf390c11d85c75553b3ea7e0efc8246

bitcoin/src/address/error.rs

@@ -1,3 +1,5 @@
+//! Error code for the address module.
+
 use core::fmt;
 
 use internals::write_err;

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.
+#[rustfmt::skip]                // Keep public re-exports separate.
-pub mod error;
+#[doc(inline)]
-pub use self::error::{Error, ParseError, UnknownAddressTypeError};
+pub use self::{
+    error::{Error, ParseError, UnknownAddressTypeError},
+};
 
 /// The different types of addresses.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]

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, Network, 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

bitcoin/src/blockdata/mod.rs

@@ -16,5 +16,9 @@ pub mod transaction;
 pub mod weight;
 pub mod witness;
 
-pub use fee_rate::FeeRate;
+#[rustfmt::skip]                // Keep public re-exports separate.
-pub use weight::Weight;
+#[doc(inline)]
+pub use self::{
+    fee_rate::FeeRate,
+    weight::Weight
+};

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;
+#[rustfmt::skip]                // Keep public re-exports separate.
-mod builder;
+#[doc(inline)]
-mod instruction;
+pub use self::{
-mod owned;
+    borrowed::*,
-mod push_bytes;
+    builder::*,
-#[cfg(test)]
+    instruction::*,
-mod tests;
+    owned::*,
-pub mod witness_program;
+    push_bytes::*,
-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::*;
 
 hashes::hash_newtype! {
     /// A hash of Bitcoin Script bytecode.

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 {

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)

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::{
+#[rustfmt::skip]                // Keep public re-exports separate.
-    deserialize, deserialize_partial, serialize, Decodable, Encodable, ReadExt, WriteExt,
+#[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;

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 {

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};

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;

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]

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};
+#[rustfmt::skip]                // Keep public re-exports separate.
-pub use crate::amount::{Amount, Denomination, SignedAmount};
+#[doc(inline)]
-pub use crate::bip32::XKeyIdentifier;
+pub use crate::{
-pub use crate::blockdata::block::{self, Block};
+    address::{Address, AddressType},
-pub use crate::blockdata::constants;
+    amount::{Amount, Denomination, SignedAmount},
-pub use crate::blockdata::fee_rate::FeeRate;
+    bip32::XKeyIdentifier,
-pub use crate::blockdata::locktime::{self, absolute, relative};
+    blockdata::block::{self, Block},
-pub use crate::blockdata::opcodes::{self, Opcode};
+    blockdata::constants,
-pub use crate::blockdata::script::witness_program::{self, WitnessProgram};
+    blockdata::fee_rate::FeeRate,
-pub use crate::blockdata::script::witness_version::{self, WitnessVersion};
+    blockdata::locktime::{self, absolute, relative},
-pub use crate::blockdata::script::{self, Script, ScriptBuf, ScriptHash, WScriptHash};
+    blockdata::opcodes::{self, Opcode},
-pub use crate::blockdata::transaction::{self, OutPoint, Sequence, Transaction, TxIn, TxOut};
+    blockdata::script::witness_program::{self, WitnessProgram},
-pub use crate::blockdata::weight::Weight;
+    blockdata::script::witness_version::{self, WitnessVersion},
-pub use crate::blockdata::witness::{self, Witness};
+    blockdata::script::{self, Script, ScriptBuf, ScriptHash, WScriptHash},
-pub use crate::consensus::encode::VarInt;
+    blockdata::transaction::{self, OutPoint, Sequence, Transaction, TxIn, TxOut},
-pub use crate::crypto::ecdsa;
+    blockdata::weight::Weight,
-pub use crate::crypto::key::{
+    blockdata::witness::{self, Witness},
-    self, PrivateKey, PubkeyHash, PublicKey, WPubkeyHash, XOnlyPublicKey,
+    consensus::encode::VarInt,
-};
+    crypto::ecdsa,
-pub use crate::crypto::sighash::{self, LegacySighash, SegwitV0Sighash, TapSighash, TapSighashTag};
+    crypto::key::{self, PrivateKey, PubkeyHash, PublicKey, WPubkeyHash, XOnlyPublicKey},
-pub use crate::hash_types::{
+    crypto::sighash::{self, LegacySighash, SegwitV0Sighash, TapSighash, TapSighashTag},
-    BlockHash, FilterHash, FilterHeader, TxMerkleNode, Txid, WitnessCommitment, Wtxid,
+    hash_types::{BlockHash, FilterHash, FilterHeader, TxMerkleNode, Txid, WitnessCommitment, Wtxid},
-};
+    merkle_tree::MerkleBlock,
-pub use crate::merkle_tree::MerkleBlock;
+    network::Network,
-pub use crate::network::Network;
+    pow::{CompactTarget, Target, Work},
-pub use crate::pow::{CompactTarget, Target, Work};
+    psbt::Psbt,
-pub use crate::psbt::Psbt;
+    sighash::{EcdsaSighashType, TapSighashType},
-pub use crate::sighash::{EcdsaSighashType, TapSighashType};
+    taproot::{TapBranchTag, TapLeafHash, TapLeafTag, TapNodeHash, TapTweakHash, TapTweakTag},
-pub use crate::taproot::{
-    TapBranchTag, TapLeafHash, TapLeafTag, TapNodeHash, TapTweakHash, TapTweakTag,
 };
 
 #[cfg(not(feature = "std"))]

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

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

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};
+use crate::prelude::*;
-pub use self::output::Output;
+use crate::psbt::raw;
-use super::serialize::Serialize;
+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 {

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]
+#[rustfmt::skip]                // Keep public re-exports separate.
-mod macros;
+#[doc(inline)]
-pub mod raw;
+pub use self::{
-pub mod serialize;
+    map::{Input, Output, PsbtSighashType},
-
+    error::Error,
-mod error;
+};
-pub use self::error::Error;
-
-mod map;
-pub use self::map::{Input, Output, PsbtSighashType};
 
 /// A Partially Signed Transaction.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]

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";

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");