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

@@ -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,11 @@
 // 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 at
+//! <http://blockstream.com/sidechains.pdf> for details of what this does.
 //!
-//! See Appendix A of the Blockstream sidechains whitepaper
-//! at <http://blockstream.com/sidechains.pdf> for details of
-//! what this does.
 
 #![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 hashes::{sha256, sha256t, Hash};

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.
 //!