From 3f5caa501fc4d4c304ec632f82eef2b7a3efc0d1 Mon Sep 17 00:00:00 2001 From: Tobin Harding Date: Sat, 6 Nov 2021 08:58:18 +1100 Subject: [PATCH] Clean up module level rustdocs Docs can always do with a bit of love. Clean up the module level (`//!`) rustdocs for all public modules. I claim uniform is better than any specific method/style. I tried to fit in with what ever was either most sane of most prevalent, therefore attaining uniformity without unnecessary code churn (one exception being the changes to headings described below). Notes: * Headings - use heading as a regular sentence for all modules e.g., ``` //! Bitcoin network messages. ``` as opposed to ``` //! # Bitcoin Network Messages ``` It was not clear which style to use so I picked a 'random' mature project and copied their style. * Added 'This module' in _most_ places as the start of the module description, however I was not religious about this one. * Fixed line length if necessary since most of our code seems to follow short (80 char) line lengths for comments anyways. * Added periods and fixed obvious (and sometimes not so obvious) grammatically errors. * Added a trailing `//!` to every block since this was almost universal already. I don't really like this one but I'm guessing it is Andrew's preferred style since its on the copyright notices as well. --- src/blockdata/block.rs | 2 +- src/blockdata/constants.rs | 4 ++-- src/blockdata/mod.rs | 2 +- src/blockdata/opcodes.rs | 4 ++-- src/blockdata/script.rs | 9 ++++----- src/blockdata/transaction.rs | 2 +- src/consensus/encode.rs | 20 +++++++++----------- src/consensus/mod.rs | 4 ++-- src/consensus/params.rs | 5 +++-- src/hash_types.rs | 12 ++++++++---- src/internal_macros.rs | 5 +++-- src/lib.rs | 11 ++++++----- src/network/address.rs | 3 ++- src/network/constants.rs | 4 ++-- src/network/message.rs | 7 +++---- src/network/message_blockdata.rs | 2 +- src/network/message_bloom.rs | 5 +++-- src/network/message_filter.rs | 3 ++- src/network/message_network.rs | 4 ++-- src/network/mod.rs | 2 +- src/network/stream_reader.rs | 10 +++++----- src/policy/mod.rs | 7 ++++--- src/serde_utils.rs | 6 ++++-- src/test_macros.rs | 5 +++-- src/util/address.rs | 9 ++++----- src/util/amount.rs | 2 +- src/util/base58.rs | 6 +++++- src/util/bip143.rs | 2 +- src/util/bip158.rs | 10 +++++----- src/util/bip32.rs | 5 +++-- src/util/contracthash.rs | 8 ++++---- src/util/ecdsa.rs | 5 +++-- src/util/hash.rs | 6 ++++-- src/util/key.rs | 4 ++-- src/util/merkleblock.rs | 3 ++- src/util/misc.rs | 6 ++++-- src/util/mod.rs | 7 ++++--- src/util/psbt/mod.rs | 3 ++- src/util/psbt/raw.rs | 3 ++- src/util/psbt/serialize.rs | 5 +++-- src/util/schnorr.rs | 5 +++-- src/util/sighash.rs | 7 ++++--- src/util/taproot.rs | 4 +++- src/util/uint.rs | 4 ++-- 44 files changed, 135 insertions(+), 107 deletions(-) diff --git a/src/blockdata/block.rs b/src/blockdata/block.rs index e5cd3f20..ed364f90 100644 --- a/src/blockdata/block.rs +++ b/src/blockdata/block.rs @@ -12,7 +12,7 @@ // If not, see . // -//! Bitcoin Block +//! Bitcoin blocks. //! //! A block is a bundle of transactions with a proof-of-work attached, //! which commits to an earlier block to form the blockchain. This diff --git a/src/blockdata/constants.rs b/src/blockdata/constants.rs index 301f1610..bdf8e2ca 100644 --- a/src/blockdata/constants.rs +++ b/src/blockdata/constants.rs @@ -12,11 +12,11 @@ // If not, see . // -//! Blockdata constants +//! Blockdata constants. //! //! This module provides various constants relating to the blockchain and //! consensus code. In particular, it defines the genesis block and its -//! single transaction +//! single transaction. //! use prelude::*; diff --git a/src/blockdata/mod.rs b/src/blockdata/mod.rs index 4713b89c..58cec8e7 100644 --- a/src/blockdata/mod.rs +++ b/src/blockdata/mod.rs @@ -12,7 +12,7 @@ // If not, see . // -//! Blockdata +//! Bitcoin block data. //! //! This module defines structures and functions for storing the blocks and //! transactions which make up the Bitcoin system. diff --git a/src/blockdata/opcodes.rs b/src/blockdata/opcodes.rs index 0a1b4dad..8d5e767c 100644 --- a/src/blockdata/opcodes.rs +++ b/src/blockdata/opcodes.rs @@ -12,10 +12,10 @@ // If not, see . // -//! Opcodes +//! Bitcoin script opcodes. //! //! Bitcoin's script uses a stack-based assembly language. This module defines -//! all of the opcodes +//! all of the opcodes for that language. //! #![allow(non_camel_case_types)] diff --git a/src/blockdata/script.rs b/src/blockdata/script.rs index 307abd48..71cf98bb 100644 --- a/src/blockdata/script.rs +++ b/src/blockdata/script.rs @@ -12,14 +12,13 @@ // If not, see . // -//! Script +//! Bitcoin scripts. //! //! Scripts define Bitcoin's digital signature scheme: a signature is formed //! from a script (the second half of which is defined by a coin to be spent, -//! and the first half provided by the spending transaction), and is valid -//! iff the script leaves `TRUE` on the stack after being evaluated. -//! Bitcoin's script is a stack-based assembly language similar in spirit to -//! Forth. +//! and the first half provided by the spending transaction), and is valid iff +//! the script leaves `TRUE` on the stack after being evaluated. Bitcoin's +//! script is a stack-based assembly language similar in spirit to Forth. //! //! This module provides the structures and functions needed to support scripts. //! diff --git a/src/blockdata/transaction.rs b/src/blockdata/transaction.rs index fd122728..c47ec3c3 100644 --- a/src/blockdata/transaction.rs +++ b/src/blockdata/transaction.rs @@ -12,7 +12,7 @@ // If not, see . // -//! Bitcoin Transaction +//! Bitcoin transactions. //! //! A transaction describes a transfer of money. It consumes previously-unspent //! transaction outputs and produces new ones, satisfying the condition to spend diff --git a/src/consensus/encode.rs b/src/consensus/encode.rs index cccbf48e..337766fa 100644 --- a/src/consensus/encode.rs +++ b/src/consensus/encode.rs @@ -12,21 +12,19 @@ // If not, see . // -//! Consensus-encodable types +//! Bitcoin consensus-encodable types. //! //! This is basically a replacement of the `Encodable` trait which does -//! normalization for endianness, etc., to ensure that the encoding -//! matches for endianness, etc., to ensure that the encoding matches +//! normalization of endianness etc., to ensure that the encoding matches //! the network consensus encoding. //! -//! Essentially, anything that must go on the -disk- or -network- must -//! be encoded using the `Encodable` trait, since this data -//! must be the same for all systems. Any data going to the -user-, e.g. -//! over JSONRPC, should use the ordinary `Encodable` trait. (This -//! should also be the same across systems, of course, but has some -//! critical differences from the network format, e.g. scripts come -//! with an opcode decode, hashes are big-endian, numbers are typically -//! big-endian decimals, etc.) +//! Essentially, anything that must go on the _disk_ or _network_ must be +//! encoded using the `Encodable` trait, since this data must be the same for +//! all systems. Any data going to the _user_ e.g., over JSONRPC, should use the +//! ordinary `Encodable` trait. (This should also be the same across systems, of +//! course, but has some critical differences from the network format e.g., +//! scripts come with an opcode decode, hashes are big-endian, numbers are +//! typically big-endian decimals, etc.) //! use prelude::*; diff --git a/src/consensus/mod.rs b/src/consensus/mod.rs index 1e302333..cdf8e6bb 100644 --- a/src/consensus/mod.rs +++ b/src/consensus/mod.rs @@ -12,9 +12,9 @@ // If not, see . // -//! Consensus +//! Bitcoin consensus. //! -//! This module defines structures, functions, and traits which are needed to +//! This module defines structures, functions, and traits that are needed to //! conform to Bitcoin consensus. //! diff --git a/src/consensus/params.rs b/src/consensus/params.rs index b3f62f45..0f6a7e2a 100644 --- a/src/consensus/params.rs +++ b/src/consensus/params.rs @@ -12,9 +12,10 @@ // If not, see . // -//! Consensus parameters +//! Bitcoin consensus parameters. //! -//! This module provides predefined set of parameters for different chains. +//! This module provides a predefined set of parameters for different Bitcoin +//! chains (such as mainnet, testnet). //! use network::constants::Network; diff --git a/src/hash_types.rs b/src/hash_types.rs index 058106de..253d993b 100644 --- a/src/hash_types.rs +++ b/src/hash_types.rs @@ -12,9 +12,13 @@ // If not, see . // -//! File defines types for hashes used throughout the library. These types are needed in order -//! to avoid mixing data of the same hash format (like SHA256d) but of different meaning -//! (transaction id, block hash etc). +//! Bitcoin hash types. +//! +//! This module defines types for hashes used throughout the library. These +//! types are needed in order to avoid mixing data of the same hash format +//! (e.g. `SHA256d`) but of different meaning (such as transaction id, block +//! hash). +//! use hashes::{Hash, sha256, sha256d, hash160}; @@ -61,4 +65,4 @@ impl_hashencode!(BlockHash); impl_hashencode!(TxMerkleNode); impl_hashencode!(WitnessMerkleNode); impl_hashencode!(FilterHash); -impl_hashencode!(FilterHeader); \ No newline at end of file +impl_hashencode!(FilterHeader); diff --git a/src/internal_macros.rs b/src/internal_macros.rs index 6476124d..52ed4ce8 100644 --- a/src/internal_macros.rs +++ b/src/internal_macros.rs @@ -12,9 +12,10 @@ // If not, see . // -//! Internal Macros +//! Internal macros. +//! +//! Macros meant to be used inside the Rust Bitcoin library. //! -//! Macros meant to be used inside the Rust Bitcoin library macro_rules! impl_consensus_encoding { ($thing:ident, $($field:ident),+) => ( diff --git a/src/lib.rs b/src/lib.rs index e01ea17c..441fba19 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -14,7 +14,7 @@ //! # Rust Bitcoin Library //! -//! This is a library for which supports the Bitcoin network protocol and associated +//! This is a library that supports the Bitcoin network protocol and associated //! primitives. It is designed for Rust programs built to work with the Bitcoin //! network. //! @@ -31,13 +31,14 @@ //! * `secp-recovery` - enables calculating public key from a signature and message. //! * `base64` - (dependency), enables encoding of PSBTs and message signatures. //! * `unstable` - enables unstable features for testing. -//! * `rand` - (dependency) makes it more convenient to generate random values. -//! * `use-serde` - (dependency) implements `serde`-based serialization and -//! deserialization -//! * `secp-lowmemory` - optimizations for low-memory devices +//! * `rand` - (dependency), makes it more convenient to generate random values. +//! * `use-serde` - (dependency), implements `serde`-based serialization and +//! deserialization. +//! * `secp-lowmemory` - optimizations for low-memory devices. //! * `no-std` - enables additional features required for this crate to be usable //! without std. Does **not** disable `std`. Depends on `hashbrown` //! and `core2`. +//! #![cfg_attr(all(not(feature = "std"), not(test)), no_std)] diff --git a/src/network/address.rs b/src/network/address.rs index 5c260049..cd43cfba 100644 --- a/src/network/address.rs +++ b/src/network/address.rs @@ -12,11 +12,12 @@ // If not, see . // -//! Bitcoin network addresses +//! Bitcoin network addresses. //! //! This module defines the structures and functions needed to encode //! network addresses in Bitcoin messages. //! + use prelude::*; use core::{fmt, iter}; diff --git a/src/network/constants.rs b/src/network/constants.rs index 0db6e98c..ed4f67d8 100644 --- a/src/network/constants.rs +++ b/src/network/constants.rs @@ -12,14 +12,14 @@ // If not, see . // -//! Network constants +//! Bitcoin network constants. //! //! This module provides various constants relating to the Bitcoin network //! protocol, such as protocol versioning and magic header bytes. //! //! The [`Network`][1] type implements the [`Decodable`][2] and //! [`Encodable`][3] traits and encodes the magic bytes of the given -//! network +//! network. //! //! [1]: enum.Network.html //! [2]: ../../consensus/encode/trait.Decodable.html diff --git a/src/network/message.rs b/src/network/message.rs index c6e4dbec..fc6f5db8 100644 --- a/src/network/message.rs +++ b/src/network/message.rs @@ -12,11 +12,10 @@ // If not, see . // -//! Network message +//! Bitcoin network messages. //! -//! This module defines the `Message` traits which are used -//! for (de)serializing Bitcoin objects for transmission on the network. It -//! also defines (de)serialization routines for many primitives. +//! This module defines the `NetworkMessage` and `RawNetworkMessage` types that +//! are used for (de)serializing Bitcoin objects for transmission on the network. //! use prelude::*; diff --git a/src/network/message_blockdata.rs b/src/network/message_blockdata.rs index 7bf7a675..fc04434d 100644 --- a/src/network/message_blockdata.rs +++ b/src/network/message_blockdata.rs @@ -12,7 +12,7 @@ // If not, see . // -//! Blockdata network messages +//! Bitcoin blockdata network messages. //! //! This module describes network messages which are used for passing //! Bitcoin data (blocks and transactions) around. diff --git a/src/network/message_bloom.rs b/src/network/message_bloom.rs index 126d43ea..e3307a03 100644 --- a/src/network/message_bloom.rs +++ b/src/network/message_bloom.rs @@ -1,5 +1,6 @@ +//! Bitcoin Connection Bloom filtering network messages. //! -//! BIP37 Connection Bloom filtering network messages +//! This module describes BIP37 Connection Bloom filtering network messages. //! use consensus::encode; @@ -61,4 +62,4 @@ pub struct FilterAdd { pub data: Vec, } -impl_consensus_encoding!(FilterAdd, data); \ No newline at end of file +impl_consensus_encoding!(FilterAdd, data); diff --git a/src/network/message_filter.rs b/src/network/message_filter.rs index 56be8b7f..b4f8bc0a 100644 --- a/src/network/message_filter.rs +++ b/src/network/message_filter.rs @@ -1,5 +1,6 @@ +//! Bitcoin Client Side Block Filtering network messages. //! -//! BIP157 Client Side Block Filtering network messages +//! This module describes BIP157 Client Side Block Filtering network messages. //! use hash_types::{BlockHash, FilterHash, FilterHeader}; diff --git a/src/network/message_network.rs b/src/network/message_network.rs index 5d96b555..e568bb71 100644 --- a/src/network/message_network.rs +++ b/src/network/message_network.rs @@ -12,10 +12,10 @@ // If not, see . // -//! Network-related network messages +//! Bitcoin network-related network messages. //! //! This module defines network messages which describe peers and their -//! capabilities +//! capabilities. //! use prelude::*; diff --git a/src/network/mod.rs b/src/network/mod.rs index 1ae3f376..e52a0ed5 100644 --- a/src/network/mod.rs +++ b/src/network/mod.rs @@ -12,7 +12,7 @@ // If not, see . // -//! Network Support +//! Bitcoin network support. //! //! This module defines support for (de)serialization and network transport //! of Bitcoin data and network messages. diff --git a/src/network/stream_reader.rs b/src/network/stream_reader.rs index 80c53a6a..4b5d61d3 100644 --- a/src/network/stream_reader.rs +++ b/src/network/stream_reader.rs @@ -12,12 +12,12 @@ // If not, see . // -//! Stream reader +//! Stream reader. //! -//! This module defines `StreamReader` struct and its implementation which is used -//! for parsing incoming stream into separate `RawNetworkMessage`s, handling assembling -//! messages from multiple packets or dealing with partial or multiple messages in the stream -//! (like can happen with reading from TCP socket) +//! This module defines the `StreamReader` struct and its implementation which +//! is used for parsing an incoming stream into separate `RawNetworkMessage`s, +//! handling assembling messages from multiple packets, or dealing with partial +//! or multiple messages in the stream (e.g. when reading from a TCP socket). //! use prelude::*; diff --git a/src/policy/mod.rs b/src/policy/mod.rs index e4e26c1f..0a865653 100644 --- a/src/policy/mod.rs +++ b/src/policy/mod.rs @@ -12,16 +12,17 @@ // If not, see . // -//! Policy +//! Bitcoin policy. //! -//! This module exposes some constants and functions used in the reference implementation and which -//! as a consequence defines some network rules. +//! This module exposes some constants and functions used in the reference +//! implementation and which, as a consequence, define some network rules. //! //! # *Warning* //! While the constants present in this module are very unlikely to change, they do not define //! Bitcoin. As such they must not be relied upon as if they were consensus rules. //! //! These values were taken from bitcoind v0.21.1 (194b9b8792d9b0798fdb570b79fa51f1d1f5ebaf). +//! use super::blockdata::constants::{MAX_BLOCK_SIGOPS_COST, WITNESS_SCALE_FACTOR}; use core::cmp; diff --git a/src/serde_utils.rs b/src/serde_utils.rs index 47e9998a..739f5eb2 100644 --- a/src/serde_utils.rs +++ b/src/serde_utils.rs @@ -1,5 +1,7 @@ - -//! Module for special serde serializations. +//! Bitcoin serde utilities. +//! +//! This module is for special serde serializations. +//! pub mod btreemap_byte_values { //! Module for serialization of BTreeMaps with hex byte values. diff --git a/src/test_macros.rs b/src/test_macros.rs index 11c46229..244aa6c9 100644 --- a/src/test_macros.rs +++ b/src/test_macros.rs @@ -12,9 +12,10 @@ // If not, see . // -//! Macros +//! Bitcoin serde macros. +//! +//! This module provides internal macros used for unit tests. //! -//! Internal macros used for unit tests #[cfg(feature = "serde")] macro_rules! serde_round_trip ( diff --git a/src/util/address.rs b/src/util/address.rs index 3a057504..d624e5c8 100644 --- a/src/util/address.rs +++ b/src/util/address.rs @@ -11,25 +11,24 @@ // If not, see . // -//! Addresses +//! Bitcoin addresses. //! -//! Support for ordinary base58 Bitcoin addresses and private keys +//! Support for ordinary base58 Bitcoin addresses and private keys. //! //! # Example: creating a new address from a randomly-generated key pair //! //! ```rust -//! //! use bitcoin::network::constants::Network; //! use bitcoin::util::address::Address; //! use bitcoin::util::ecdsa; //! use bitcoin::secp256k1::Secp256k1; //! use bitcoin::secp256k1::rand::thread_rng; //! -//! // Generate random key pair +//! // Generate random key pair. //! let s = Secp256k1::new(); //! let public_key = ecdsa::PublicKey::new(s.generate_keypair(&mut thread_rng()).1); //! -//! // Generate pay-to-pubkey-hash address +//! // Generate pay-to-pubkey-hash address. //! let address = Address::p2pkh(&public_key, Network::Bitcoin); //! ``` diff --git a/src/util/amount.rs b/src/util/amount.rs index b9a90608..dc310c20 100644 --- a/src/util/amount.rs +++ b/src/util/amount.rs @@ -8,7 +8,7 @@ // If not, see . // -//! Amounts +//! Bitcoin amounts. //! //! This module mainly introduces the [Amount] and [SignedAmount] types. //! We refer to the documentation on the types for more information. diff --git a/src/util/base58.rs b/src/util/base58.rs index 486b7c16..94c4069e 100644 --- a/src/util/base58.rs +++ b/src/util/base58.rs @@ -12,7 +12,11 @@ // If not, see . // -//! Base58 encoder and decoder +//! Base58 encoder and decoder. +//! +//! This module provides functions for encoding and decoding base58 slices and +//! strings respectively. +//! use prelude::*; diff --git a/src/util/bip143.rs b/src/util/bip143.rs index 23b18967..dc60eb35 100644 --- a/src/util/bip143.rs +++ b/src/util/bip143.rs @@ -11,7 +11,7 @@ // If not, see . // -//! BIP143 Implementation +//! BIP143 implementation. //! //! Implementation of BIP143 Segwit-style signatures. Should be sufficient //! to create signatures for Segwit transactions (which should be pushed into diff --git a/src/util/bip158.rs b/src/util/bip158.rs index 479b551a..762c4de9 100644 --- a/src/util/bip158.rs +++ b/src/util/bip158.rs @@ -16,12 +16,12 @@ // on 11. June 2019 which is licensed under Apache, that file specifically // was written entirely by Tamas Blummer, who is re-licensing its contents here as CC0. +//! BIP158 Compact Block Filters for light clients. //! -//! # BIP158 Compact Block Filters for Light Clients -//! -//! Implements a structure for compact filters on block data, for use in the BIP 157 light client protocol. -//! The filter construction proposed is an alternative to Bloom filters, as used in BIP 37, -//! that minimizes filter size by using Golomb-Rice coding for compression. +//! This module implements a structure for compact filters on block data, for +//! use in the BIP 157 light client protocol. The filter construction proposed +//! is an alternative to Bloom filters, as used in BIP 37, that minimizes filter +//! size by using Golomb-Rice coding for compression. //! //! ## Example //! diff --git a/src/util/bip32.rs b/src/util/bip32.rs index 520ead88..a2ec9668 100644 --- a/src/util/bip32.rs +++ b/src/util/bip32.rs @@ -11,10 +11,11 @@ // If not, see . // -//! BIP32 Implementation +//! BIP32 implementation. //! //! Implementation of BIP32 hierarchical deterministic wallets, as defined -//! at +//! at . +//! use prelude::*; diff --git a/src/util/contracthash.rs b/src/util/contracthash.rs index 24e14929..90fc0112 100644 --- a/src/util/contracthash.rs +++ b/src/util/contracthash.rs @@ -12,11 +12,11 @@ // If not, see . // -//! Pay-to-contract-hash support +//! Pay-to-contract-hash support. +//! +//! See Appendix A of the Blockstream sidechains whitepaper at +//! for details of what this does. //! -//! See Appendix A of the Blockstream sidechains whitepaper -//! at for details of -//! what this does. #![cfg_attr(not(test), deprecated)] diff --git a/src/util/ecdsa.rs b/src/util/ecdsa.rs index aecf897d..33e3685d 100644 --- a/src/util/ecdsa.rs +++ b/src/util/ecdsa.rs @@ -11,9 +11,10 @@ // If not, see . // -//! ECDSA Bitcoin Keys +//! ECDSA Bitcoin keys. //! -//! ECDSA keys used in Bitcoin that can be roundtrip (de)serialized. +//! This module provides ECDSA keys used in Bitcoin that can be roundtrip +//! (de)serialized. //! use prelude::*; diff --git a/src/util/hash.rs b/src/util/hash.rs index 3f108097..d5d7cabb 100644 --- a/src/util/hash.rs +++ b/src/util/hash.rs @@ -11,9 +11,11 @@ // If not, see . // -//! Hash functions +//! Bitcoin hash functions. +//! +//! This module provides utility functions related to hashing data, including +//! merkleization. //! -//! Utility functions related to hashing data, including merkleization use prelude::*; diff --git a/src/util/key.rs b/src/util/key.rs index d26ee742..9cd44e73 100644 --- a/src/util/key.rs +++ b/src/util/key.rs @@ -11,9 +11,9 @@ // If not, see . // -//! Bitcoin Keys +//! Bitcoin keys. //! -//! Keys used in Bitcoin that can be roundtrip (de)serialized. +//! This module provides keys used in Bitcoin that can be roundtrip (de)serialized. //! #[deprecated(since = "0.26.1", note = "Please use `util::ecdsa` instead")] diff --git a/src/util/merkleblock.rs b/src/util/merkleblock.rs index 998277e5..1f9f2950 100644 --- a/src/util/merkleblock.rs +++ b/src/util/merkleblock.rs @@ -18,7 +18,7 @@ // Distributed under the MIT software license, see the accompanying // file COPYING or http://www.opensource.org/licenses/mit-license.php. -//! Merkle Block and Partial Merkle Tree +//! Merkle Block and Partial Merkle Tree. //! //! Support proofs that transaction(s) belong to a block. //! @@ -51,6 +51,7 @@ //! assert_eq!(1, index.len()); //! assert_eq!(1, index[0]); //! ``` + use prelude::*; use io; diff --git a/src/util/misc.rs b/src/util/misc.rs index 553fa6a2..3da4a82f 100644 --- a/src/util/misc.rs +++ b/src/util/misc.rs @@ -12,9 +12,11 @@ // If not, see . // -//! Miscellaneous functions +//! Miscellaneous functions. +//! +//! This module provides various utility functions including secp256k1 signature +//! recovery when library is used with the `secp-recovery` feature. //! -//! Various utility functions use prelude::*; diff --git a/src/util/mod.rs b/src/util/mod.rs index e6662e1a..d3aa5d80 100644 --- a/src/util/mod.rs +++ b/src/util/mod.rs @@ -12,9 +12,10 @@ // If not, see . // -//! Utility functions +//! Utility functions. +//! +//! Functions needed by all parts of the Bitcoin library. //! -//! Functions needed by all parts of the Bitcoin library pub mod ecdsa; pub mod key; @@ -128,4 +129,4 @@ pub(crate) fn read_to_end(mut d: D) -> Result, io::Error> { }; } Ok(result) -} \ No newline at end of file +} diff --git a/src/util/psbt/mod.rs b/src/util/psbt/mod.rs index 1f17d3fc..96b3c1b3 100644 --- a/src/util/psbt/mod.rs +++ b/src/util/psbt/mod.rs @@ -12,11 +12,12 @@ // If not, see . // -//! # Partially Signed Transactions +//! Partially Signed Bitcoin Transactions. //! //! Implementation of BIP174 Partially Signed Bitcoin Transaction Format as //! defined at //! except we define PSBTs containing non-standard SigHash types as invalid. +//! use blockdata::script::Script; use blockdata::transaction::Transaction; diff --git a/src/util/psbt/raw.rs b/src/util/psbt/raw.rs index dbe99228..1a4f1fa1 100644 --- a/src/util/psbt/raw.rs +++ b/src/util/psbt/raw.rs @@ -12,10 +12,11 @@ // If not, see . // -//! # Raw PSBT Key-Value Pairs +//! Raw PSBT key-value pairs. //! //! Raw PSBT key-value pairs as defined at //! . +//! use prelude::*; use core::fmt; diff --git a/src/util/psbt/serialize.rs b/src/util/psbt/serialize.rs index 7cbf6ee7..f2e31e0d 100644 --- a/src/util/psbt/serialize.rs +++ b/src/util/psbt/serialize.rs @@ -12,10 +12,11 @@ // If not, see . // -//! # PSBT Serialization +//! PSBT serialization. //! //! Defines traits used for (de)serializing PSBT values into/from raw -//! bytes in PSBT key-value pairs. +//! bytes from/as PSBT key-value pairs. +//! use prelude::*; diff --git a/src/util/schnorr.rs b/src/util/schnorr.rs index 473541c5..df1c151b 100644 --- a/src/util/schnorr.rs +++ b/src/util/schnorr.rs @@ -11,9 +11,10 @@ // If not, see . // -//! Schnorr Bitcoin Keys +//! Schnorr Bitcoin keys. //! -//! Schnorr keys used in Bitcoin, reexporting Secp256k1 Schnorr key types +//! This module provides Schnorr keys used in Bitcoin, reexporting Secp256k1 +//! Schnorr key types. //! pub use secp256k1::schnorrsig::{PublicKey, KeyPair}; diff --git a/src/util/sighash.rs b/src/util/sighash.rs index df4e3082..630fc279 100644 --- a/src/util/sighash.rs +++ b/src/util/sighash.rs @@ -12,11 +12,12 @@ // If not, see . // -//! # Generalized, efficient, signature hash implementation +//! Generalized, efficient, signature hash implementation. //! -//! Implementation of the algorithm to compute the message to be signed according to [Bip341](https://github.com/bitcoin/bips/blob/150ab6f5c3aca9da05fccc5b435e9667853407f4/bip-0341.mediawiki), +//! Implementation of the algorithm to compute the message to be signed according to +//! [Bip341](https://github.com/bitcoin/bips/blob/150ab6f5c3aca9da05fccc5b435e9667853407f4/bip-0341.mediawiki), //! [Bip143](https://github.com/bitcoin/bips/blob/99701f68a88ce33b2d0838eb84e115cef505b4c2/bip-0143.mediawiki) -//! and legacy (before Bip143) +//! and legacy (before Bip143). //! pub use blockdata::transaction::SigHashType as LegacySigHashType; diff --git a/src/util/taproot.rs b/src/util/taproot.rs index 472edb08..8cb02174 100644 --- a/src/util/taproot.rs +++ b/src/util/taproot.rs @@ -11,7 +11,9 @@ // If not, see . // -//! Taproot +//! Bitcoin Taproot. +//! +//! This module provides support for taproot tagged hashes. //! use hashes::{sha256, sha256t, Hash}; diff --git a/src/util/uint.rs b/src/util/uint.rs index 3559c1b6..5dbfcf84 100644 --- a/src/util/uint.rs +++ b/src/util/uint.rs @@ -12,9 +12,9 @@ // If not, see . // -//! Big unsigned integer types +//! Big unsigned integer types. //! -//! Implementation of a various large-but-fixed sized unsigned integer types. +//! Implementation of various large-but-fixed sized unsigned integer types. //! The functions here are designed to be fast. //!