Update docstrings of Storage fields relating to blocks

.changelog/unreleased/miscellaneous/650-last-block.md

@@ -0,0 +1,2 @@
+- Improve some docstrings relating to block heights
+  ([#650](https://github.com/anoma/namada/pull/650))

apps/src/lib/node/ledger/shell/finalize_block.rs

@@ -259,21 +259,16 @@ where
             .begin_block(hash, height)
             .expect("Beginning a block shouldn't fail");
 
+        let header_time = header.time;
         self.storage
             .set_header(header)
             .expect("Setting a header shouldn't fail");
 
         self.byzantine_validators = byzantine_validators;
 
-        let header = self
-            .storage
-            .header
-            .as_ref()
-            .expect("Header must have been set in prepare_proposal.");
-        let time = header.time;
         let new_epoch = self
             .storage
-            .update_epoch(height, time)
+            .update_epoch(height, header_time)
             .expect("Must be able to update epoch");
 
         self.slash();

shared/src/ledger/storage/mod.rs

@@ -52,13 +52,17 @@ where
     pub db: D,
     /// The ID of the chain
     pub chain_id: ChainId,
-    /// The storage for the current (yet to be committed) block
+    /// Block storage data
     pub block: BlockStorage<H>,
-    /// The latest block header
+    /// During `FinalizeBlock`, this is the header of the block that is
+    /// going to be committed. After a block is committed, this is reset to
+    /// `None` until the next `FinalizeBlock` phase is reached.
     pub header: Option<Header>,
-    /// The height of the committed block
+    /// The height of the most recently committed block, or `BlockHeight(0)` if
+    /// no block has been committed for this chain yet.
     pub last_height: BlockHeight,
-    /// The epoch of the committed block
+    /// The epoch of the most recently committed block. If it is `Epoch(0)`,
+    /// then no block may have been committed for this chain yet.
     pub last_epoch: Epoch,
     /// Minimum block height at which the next epoch may start
     pub next_epoch_min_start_height: BlockHeight,
@@ -76,11 +80,19 @@ where
 pub struct BlockStorage<H: StorageHasher> {
     /// Merkle tree of all the other data in block storage
     pub tree: MerkleTree<H>,
-    /// Hash of the block
+    /// During `FinalizeBlock`, this is updated to be the hash of the block
+    /// that is going to be committed. If it is `BlockHash::default()`,
+    /// then no `FinalizeBlock` stage has been reached yet.
     pub hash: BlockHash,
-    /// Height of the block (i.e. the level)
+    /// From the start of `FinalizeBlock` until the end of `Commit`, this is
+    /// height of the block that is going to be committed. Otherwise, it is the
+    /// height of the most recently committed block, or `BlockHeight(0)` if no
+    /// block has been committed yet.
     pub height: BlockHeight,
-    /// Epoch of the block
+    /// From the start of `FinalizeBlock` until the end of `Commit`, this is
+    /// height of the block that is going to be committed. Otherwise it is the
+    /// epoch of the most recently committed block, or `Epoch(0)` if no block
+    /// has been committed yet.
     pub epoch: Epoch,
     /// Predecessor block epochs
     pub pred_epochs: Epochs,
@@ -516,12 +528,12 @@ where
         (self.chain_id.to_string(), CHAIN_ID_LENGTH as _)
     }
 
-    /// Get the current (yet to be committed) block height
+    /// Get the block height
     pub fn get_block_height(&self) -> (BlockHeight, u64) {
         (self.block.height, MIN_STORAGE_GAS)
     }
 
-    /// Get the current (yet to be committed) block hash
+    /// Get the block hash
     pub fn get_block_hash(&self) -> (BlockHash, u64) {
         (self.block.hash.clone(), BLOCK_HASH_LENGTH as _)
     }