chain: doc tweaks (mostly block::)

zebra-chain/src/amount.rs

@@ -3,7 +3,7 @@
 //! The [`Amount`] type is parameterized by a [`Constraint`] implementation that
 //! declares the range of allowed values. In contrast to regular arithmetic
 //! operations, which return values, arithmetic on [`Amount`]s returns
-//! [`Result`]s.
+//! [`Result`](std::result::Result)s.
 
 use std::{
     convert::{TryFrom, TryInto},

zebra-chain/src/block.rs

@@ -28,12 +28,7 @@ use crate::transaction::Transaction;
 #[cfg(test)]
 use proptest_derive::Arbitrary;
 
-/// A block in your blockchain.
-///
-/// A block is a data structure with two fields:
-///
-/// Block header: a data structure containing the block's metadata
-/// Transactions: an array (vector in Rust) of transactions
+/// A Zcash block, containing a header and a list of transactions.
 #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
 #[cfg_attr(test, derive(Arbitrary))]
 pub struct Block {

zebra-chain/src/block/hash.rs

@@ -10,18 +10,11 @@ use crate::serialization::{
 
 use super::Header;
 
-/// A SHA-256d hash of a BlockHeader.
+/// A hash of a block, used to identify blocks and link blocks into a chain. ⛓️
 ///
-/// This is useful when one block header is pointing to its parent
-/// block header in the block chain. ⛓️
-///
-/// This is usually called a 'block hash', as it is frequently used
-/// to identify the entire block, since the hash preimage includes
-/// the merkle root of the transactions in this block. But
-/// _technically_, this is just a hash of the block _header_, not
-/// the direct bytes of the transactions as well as the header. So
-/// for now I want to call it a `BlockHeaderHash` because that's
-/// more explicit.
+/// Technically, this is the (SHA256d) hash of a block *header*, but since the
+/// block header includes the Merkle root of the transaction Merkle tree, it
+/// binds the entire contents of the block and is used to identify entire blocks.
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)]
 #[cfg_attr(test, derive(Arbitrary))]
 pub struct Hash(pub [u8; 32]);

zebra-chain/src/block/header.rs

@@ -5,7 +5,7 @@ use crate::work::{difficulty::CompactDifficulty, equihash::Solution};
 
 use super::{merkle, Error, Hash};
 
-/// Block header.
+/// A block header, containing metadata about a block.
 ///
 /// How are blocks chained together? They are chained together via the
 /// backwards reference (previous header hash) present in the block
@@ -23,16 +23,18 @@ pub struct Header {
     /// interpreted as an `i32`.
     pub version: u32,
 
-    /// A SHA-256d hash in internal byte order of the previous block’s
-    /// header. This ensures no previous block can be changed without
-    /// also changing this block’s header.
+    /// The hash of the previous block, used to create a chain of blocks back to
+    /// the genesis block.
+    ///
+    /// This ensures no previous block can be changed without also changing this
+    /// block’s header.
     pub previous_block_hash: Hash,
 
-    /// A SHA-256d hash in internal byte order. The merkle root is
-    /// derived from the SHA256d hashes of all transactions included
-    /// in this block as assembled in a binary tree, ensuring that
-    /// none of those transactions can be modied without modifying the
-    /// header.
+    /// The root of the transaction Merkle tree.
+    ///
+    /// The Merkle root is derived from the SHA256d hashes of all transactions
+    /// included in this block as assembled in a binary tree, ensuring that none
+    /// of those transactions can be modied without modifying the header.
     pub merkle_root: merkle::Root,
 
     /// Some kind of root hash.

zebra-chain/src/block/height.rs

@@ -1,6 +1,6 @@
 use crate::serialization::SerializationError;
 
-/// A u32 which represents a block height value.
+/// The height of a block is the length of the chain back to the genesis block.
 ///
 /// # Invariants
 ///

zebra-chain/src/block/merkle.rs

@@ -1,5 +1,4 @@
-//! A binary hash tree of SHA256d (two rounds of SHA256) hashes for
-//! node values.
+//! The Bitcoin-inherited Merkle tree of transactions.
 #![allow(clippy::unit_arg)]
 
 use std::{fmt, io};