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
This commit is contained in:
Andrew Poelstra 2023-11-14 22:49:56 +00:00
commit c0de0f7bde
No known key found for this signature in database
GPG Key ID: C588D63CE41B97C1
19 changed files with 138 additions and 87 deletions

View File

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

View File

@ -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)]

View File

@ -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

View File

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

View File

@ -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.

View File

@ -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 {

View File

@ -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)

View File

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

View File

@ -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 {

View File

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

View File

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

View File

@ -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]

View File

@ -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"))]

View File

@ -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

View File

@ -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

View File

@ -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 {

View File

@ -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)]

View File

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

View File

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