Merge pull request #689 from tcharding/module-rustdocs

Clean up module level rustdocs

src/blockdata/block.rs

@@ -12,7 +12,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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

src/blockdata/constants.rs

@@ -12,11 +12,11 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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::*;

src/blockdata/mod.rs

@@ -12,7 +12,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Blockdata
+//! Bitcoin block data.
 //!
 //! This module defines structures and functions for storing the blocks and
 //! transactions which make up the Bitcoin system.

src/blockdata/opcodes.rs

@@ -12,10 +12,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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)]

src/blockdata/script.rs

@@ -12,14 +12,13 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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
+//! and the first half provided by the spending transaction), and is valid iff
-//! iff the script leaves `TRUE` on the stack after being evaluated.
+//! the script leaves `TRUE` on the stack after being evaluated. Bitcoin's
-//! Bitcoin's script is a stack-based assembly language similar in spirit to
+//! script is a stack-based assembly language similar in spirit to Forth.
-//! Forth.
 //!
 //! This module provides the structures and functions needed to support scripts.
 //!

src/blockdata/transaction.rs

@@ -12,7 +12,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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

src/consensus/encode.rs

@@ -12,21 +12,19 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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
+//! normalization of endianness etc., to ensure that the encoding matches
-//! matches for endianness, etc., to ensure that the encoding matches
 //! the network consensus encoding.
 //!
-//! Essentially, anything that must go on the -disk- or -network- must
+//! Essentially, anything that must go on the _disk_ or _network_ must be
-//! be encoded using the `Encodable` trait, since this data
+//! encoded using the `Encodable` trait, since this data must be the same for
-//! must be the same for all systems. Any data going to the -user-, e.g.
+//! all systems. Any data going to the _user_ e.g., over JSONRPC, should use the
-//! over JSONRPC, should use the ordinary `Encodable` trait. (This
+//! ordinary `Encodable` trait. (This should also be the same across systems, of
-//! should also be the same across systems, of course, but has some
+//! course, but has some critical differences from the network format e.g.,
-//! critical differences from the network format, e.g. scripts come
+//! scripts come with an opcode decode, hashes are big-endian, numbers are
-//! with an opcode decode, hashes are big-endian, numbers are typically
+//! typically big-endian decimals, etc.)
-//! big-endian decimals, etc.)
 //!
 
 use prelude::*;

src/consensus/mod.rs

@@ -12,9 +12,9 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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.
 //!
 

src/consensus/params.rs

@@ -12,9 +12,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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;

src/hash_types.rs

@@ -12,9 +12,13 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! File defines types for hashes used throughout the library. These types are needed in order
+//! Bitcoin hash types.
-//! to avoid mixing data of the same hash format (like SHA256d) but of different meaning
+//!
-//! (transaction id, block hash etc).
+//! 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};
 

src/internal_macros.rs

@@ -12,9 +12,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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),+) => (

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.
+//! * `rand` - (dependency), makes it more convenient to generate random values.
-//! * `use-serde` - (dependency) implements `serde`-based serialization and
+//! * `use-serde` - (dependency), implements `serde`-based serialization and
-//!                 deserialization
+//!                 deserialization.
-//! * `secp-lowmemory` - optimizations for low-memory devices
+//! * `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)]
 

src/network/address.rs

@@ -12,11 +12,12 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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};

src/network/constants.rs

@@ -12,14 +12,14 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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

src/network/message.rs

@@ -12,11 +12,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Network message
+//! Bitcoin network messages.
 //!
-//! This module defines the `Message` traits which are used
+//! This module defines the `NetworkMessage` and `RawNetworkMessage` types that
-//! for (de)serializing Bitcoin objects for transmission on the network. It
+//! are used for (de)serializing Bitcoin objects for transmission on the network.
-//! also defines (de)serialization routines for many primitives.
 //!
 
 use prelude::*;

src/network/message_blockdata.rs

@@ -12,7 +12,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Blockdata network messages
+//! Bitcoin blockdata network messages.
 //!
 //! This module describes network messages which are used for passing
 //! Bitcoin data (blocks and transactions) around.

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;

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

src/network/message_network.rs

@@ -12,10 +12,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Network-related network messages
+//! Bitcoin network-related network messages.
 //!
 //! This module defines network messages which describe peers and their
-//! capabilities
+//! capabilities.
 //!
 
 use prelude::*;

src/network/mod.rs

@@ -12,7 +12,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Network Support
+//! Bitcoin network support.
 //!
 //! This module defines support for (de)serialization and network transport
 //! of Bitcoin data and network messages.

src/network/stream_reader.rs

@@ -12,12 +12,12 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Stream reader
+//! Stream reader.
 //!
-//! This module defines `StreamReader` struct and its implementation which is used
+//! This module defines the `StreamReader` struct and its implementation which
-//! for parsing incoming stream into separate `RawNetworkMessage`s, handling assembling
+//! is used for parsing an incoming stream into separate `RawNetworkMessage`s,
-//! messages from multiple packets or dealing with partial or multiple messages in the stream
+//! handling assembling messages from multiple packets, or dealing with partial
-//! (like can happen with reading from TCP socket)
+//! or multiple messages in the stream (e.g. when reading from a TCP socket).
 //!
 
 use prelude::*;

src/policy/mod.rs

@@ -12,16 +12,17 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Policy
+//! Bitcoin policy.
 //!
-//! This module exposes some constants and functions used in the reference implementation and which
+//! This module exposes some constants and functions used in the reference
-//! as a consequence defines some network rules.
+//! 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;

src/serde_utils.rs

@@ -1,5 +1,7 @@
-
+//! Bitcoin serde utilities.
-//! Module for special serde serializations.
+//!
+//! This module is for special serde serializations.
+//!
 
 pub mod btreemap_byte_values {
     //! Module for serialization of BTreeMaps with hex byte values.

src/test_macros.rs

@@ -12,9 +12,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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 (

src/util/address.rs

@@ -11,25 +11,24 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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);
 //! ```
 

src/util/amount.rs

@@ -8,7 +8,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Amounts
+//! Bitcoin amounts.
 //!
 //! This module mainly introduces the [Amount] and [SignedAmount] types.
 //! We refer to the documentation on the types for more information.

src/util/base58.rs

@@ -12,7 +12,11 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Base58 encoder and decoder
+//! Base58 encoder and decoder.
+//!
+//! This module provides functions for encoding and decoding base58 slices and
+//! strings respectively.
+//!
 
 use prelude::*;
 

src/util/bip143.rs

@@ -11,7 +11,7 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! BIP143 Implementation
+//! BIP143 implementation.
 //!
 //! Implementation of BIP143 Segwit-style signatures. Should be sufficient
 //! to create signatures for Segwit transactions (which should be pushed into

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
+//! This module implements a structure for compact filters on block data, for
-//!
+//! use in the BIP 157 light client protocol. The filter construction proposed
-//! Implements a structure for compact filters on block data, for use in the BIP 157 light client protocol.
+//! is an alternative to Bloom filters, as used in BIP 37, that minimizes filter
-//! The filter construction proposed is an alternative to Bloom filters, as used in BIP 37,
+//! size by using Golomb-Rice coding for compression.
-//! that minimizes filter size by using Golomb-Rice coding for compression.
 //!
 //! ## Example
 //!

src/util/bip32.rs

@@ -11,10 +11,11 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! BIP32 Implementation
+//! BIP32 implementation.
 //!
 //! Implementation of BIP32 hierarchical deterministic wallets, as defined
-//! at <https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki>
+//! at <https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki>.
+//!
 
 use prelude::*;
 

src/util/contracthash.rs

@@ -12,11 +12,12 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Pay-to-contract-hash support
+//! Pay-to-contract-hash support.
 //!
-//! See Appendix A of the Blockstream sidechains whitepaper
+//! See Appendix A of the Blockstream sidechains whitepaper at
-//! at <http://blockstream.com/sidechains.pdf> for details of
+//! <http://blockstream.com/sidechains.pdf> for details of what this does.
-//! what this does.
+//!
+//! This module is deprecated.
 
 #![cfg_attr(not(test), deprecated)]
 

src/util/ecdsa.rs

@@ -11,9 +11,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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::*;

src/util/hash.rs

@@ -11,9 +11,11 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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::*;
 

src/util/key.rs

@@ -11,9 +11,9 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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")]

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;

src/util/misc.rs

@@ -12,9 +12,11 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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::*;
 

src/util/mod.rs

@@ -12,9 +12,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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;

src/util/psbt/mod.rs

@@ -12,11 +12,12 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # Partially Signed Transactions
+//! Partially Signed Bitcoin Transactions.
 //!
 //! Implementation of BIP174 Partially Signed Bitcoin Transaction Format as
 //! defined at <https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki>
 //! except we define PSBTs containing non-standard SigHash types as invalid.
+//!
 
 use blockdata::script::Script;
 use blockdata::transaction::Transaction;

src/util/psbt/raw.rs

@@ -12,10 +12,11 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # Raw PSBT Key-Value Pairs
+//! Raw PSBT key-value pairs.
 //!
 //! Raw PSBT key-value pairs as defined at
 //! <https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki>.
+//!
 
 use prelude::*;
 use core::fmt;

src/util/psbt/serialize.rs

@@ -12,10 +12,11 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # 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::*;
 

src/util/schnorr.rs

@@ -11,9 +11,10 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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};

src/util/sighash.rs

@@ -12,11 +12,12 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! # 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;

src/util/taproot.rs

@@ -11,7 +11,9 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! Taproot
+//! Bitcoin Taproot.
+//!
+//! This module provides support for taproot tagged hashes.
 //!
 use prelude::*;
 use io;

src/util/uint.rs

@@ -12,9 +12,9 @@
 // If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
 //
 
-//! 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.
 //!