From 146d5e83d1744f1ae6143e472e7a24bde3110e16 Mon Sep 17 00:00:00 2001
From: Tobin Harding <me@tobin.cc>
Date: Wed, 9 Mar 2022 12:05:49 +1100
Subject: [PATCH] Improve docs for blockdata::block

Improve the rustdocs for the `blockdata::block` module:

- Use full sentences (capitalisation and full stop)
- Use third person tense instead of imperative
- Improve wording if needed
---
 src/blockdata/block.rs | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/src/blockdata/block.rs b/src/blockdata/block.rs
index 282d4375..d5749151 100644
--- a/src/blockdata/block.rs
+++ b/src/blockdata/block.rs
@@ -44,30 +44,30 @@ use VarInt;
 pub struct BlockHeader {
     /// The protocol version. Should always be 1.
     pub version: i32,
-    /// Reference to the previous block in the chain
+    /// Reference to the previous block in the chain.
     pub prev_blockhash: BlockHash,
-    /// The root hash of the merkle tree of transactions in the block
+    /// The root hash of the merkle tree of transactions in the block.
     pub merkle_root: TxMerkleNode,
-    /// The timestamp of the block, as claimed by the miner
+    /// The timestamp of the block, as claimed by the miner.
     pub time: u32,
     /// The target value below which the blockhash must lie, encoded as a
-    /// a float (with well-defined rounding, of course)
+    /// a float (with well-defined rounding, of course).
     pub bits: u32,
-    /// The nonce, selected to obtain a low enough blockhash
+    /// The nonce, selected to obtain a low enough blockhash.
     pub nonce: u32,
 }
 
 impl_consensus_encoding!(BlockHeader, version, prev_blockhash, merkle_root, time, bits, nonce);
 
 impl BlockHeader {
-    /// Return the block hash.
+    /// Returns the block hash.
     pub fn block_hash(&self) -> BlockHash {
         let mut engine = BlockHash::engine();
         self.consensus_encode(&mut engine).expect("engines don't error");
         BlockHash::from_engine(engine)
     }
 
-    /// Computes the target [0, T] that a blockhash must land in to be valid
+    /// Computes the target [0, T] that a blockhash must land in to be valid.
     pub fn target(&self) -> Uint256 {
         Self::u256_from_compact_target(self.bits)
     }
@@ -125,7 +125,7 @@ impl BlockHeader {
         compact | (size << 24) as u32
     }
 
-    /// Compute the popular "difficulty" measure for mining
+    /// Computes the popular "difficulty" measure for mining.
     pub fn difficulty(&self, network: Network) -> u64 {
         (max_target(network) / self.target()).low_u64()
     }
@@ -143,7 +143,7 @@ impl BlockHeader {
         if hash <= target { Ok(block_hash) } else { Err(BlockBadProofOfWork) }
     }
 
-    /// Returns the total work of the block
+    /// Returns the total work of the block.
     pub fn work(&self) -> Uint256 {
         // 2**256 / (target + 1) == ~target / (target+1) + 1    (eqn shamelessly stolen from bitcoind)
         let mut ret = !self.target();
@@ -169,7 +169,7 @@ pub struct Block {
 impl_consensus_encoding!(Block, header, txdata);
 
 impl Block {
-    /// Return the block hash.
+    /// Returns the block hash.
     pub fn block_hash(&self) -> BlockHash {
         self.header.block_hash()
     }
@@ -216,7 +216,7 @@ impl Block {
         false
     }
 
-    /// Compute the transaction merkle root.
+    /// Computes the transaction merkle root.
     pub fn compute_merkle_root(&self) -> Option<TxMerkleNode> {
         let hashes = self.txdata.iter().map(|obj| obj.txid().as_hash());
         bitcoin_merkle_root(hashes).map(|h| h.into())
@@ -228,7 +228,7 @@ impl Block {
         self.compute_merkle_root()
     }
 
-    /// compute witness commitment for the transaction list
+    /// Computes the witness commitment for the block's transaction list.
     pub fn compute_witness_commitment (witness_root: &WitnessMerkleNode, witness_reserved_value: &[u8]) -> WitnessCommitment {
         let mut encoder = WitnessCommitment::engine();
         witness_root.consensus_encode(&mut encoder).expect("engines don't error");
@@ -236,7 +236,7 @@ impl Block {
         WitnessCommitment::from_engine(encoder)
     }
 
-    /// Merkle root of transactions hashed for witness
+    /// Computes the merkle root of transactions hashed for witness.
     pub fn witness_root(&self) -> Option<WitnessMerkleNode> {
         let hashes = self.txdata.iter().enumerate().map(|(i, t)|
             if i == 0 {
@@ -274,7 +274,7 @@ impl Block {
         base_weight + txs_weight
     }
 
-    /// Get the coinbase transaction, if one is present.
+    /// Returns the coinbase transaction, if one is present.
     pub fn coinbase(&self) -> Option<&Transaction> {
         self.txdata.first()
     }