From d5dc4c6d9cdfc5382bc2d4112b121b9cd6564c09 Mon Sep 17 00:00:00 2001
From: Kris Nuttycombe <kris@nutty.land>
Date: Wed, 20 Sep 2023 12:53:45 -0600
Subject: [PATCH] zcash_client_backend: Document `data_api::ScannedBlock`

Fixes #885
---
 zcash_client_backend/src/data_api.rs | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/zcash_client_backend/src/data_api.rs b/zcash_client_backend/src/data_api.rs
index e50fac38c..d7431680d 100644
--- a/zcash_client_backend/src/data_api.rs
+++ b/zcash_client_backend/src/data_api.rs
@@ -456,6 +456,7 @@ pub struct ScannedBlock<Nf> {
 }
 
 impl<Nf> ScannedBlock<Nf> {
+    /// Constructs a new `ScannedBlock`
     pub fn from_parts(
         metadata: BlockMetadata,
         block_time: u32,
@@ -472,34 +473,53 @@ impl<Nf> ScannedBlock<Nf> {
         }
     }
 
+    /// Returns the height of the block that was scanned.
     pub fn height(&self) -> BlockHeight {
         self.metadata.block_height
     }
 
+    /// Returns the block hash of the block that was scanned.
     pub fn block_hash(&self) -> BlockHash {
         self.metadata.block_hash
     }
 
+    /// Returns the block time of the block that was scanned.
     pub fn block_time(&self) -> u32 {
         self.block_time
     }
 
+    /// Returns the metadata describing the state of the note commitment trees as of the end of the
+    /// scanned block. 
+    ///
+    /// The metadata returned from this method is guaranteed to be consistent with what is returned
+    /// by [`Self::height`] and [`Self::block_hash`].
     pub fn metadata(&self) -> &BlockMetadata {
         &self.metadata
     }
 
+    /// Returns the list of transactions from the block that are relevant to the wallet.
     pub fn transactions(&self) -> &[WalletTx<Nf>] {
         &self.transactions
     }
 
+    /// Returns the vector of Sapling nullifiers for each transaction in the block.
+    ///
+    /// The returned tuple is keyed by both transaction ID and the index of the transaction within
+    /// the block, so that either the txid or the combination of the block hash available from
+    /// [`Self::block_hash`] and returned transaction index may be used to uniquely identify the
+    /// transaction, depending upon the needs of the caller.
     pub fn sapling_nullifier_map(&self) -> &[(TxId, u16, Vec<sapling::Nullifier>)] {
         &self.sapling_nullifier_map
     }
 
+    /// Returns the ordered list of Sapling note commitments to be added to the note commitment
+    /// tree.
     pub fn sapling_commitments(&self) -> &[(sapling::Node, Retention<BlockHeight>)] {
         &self.sapling_commitments
     }
 
+    /// Consumes `self` and returns the list of Sapling note commitments associated with the
+    /// scanned block as an owned value.
     pub fn into_sapling_commitments(self) -> Vec<(sapling::Node, Retention<BlockHeight>)> {
         self.sapling_commitments
     }