Merge pull request #979 from nuttycom/wallet/doc_updates

zcash_client_backend: Update API documentation.

zcash_client_backend/src/data_api.rs

@@ -257,7 +257,11 @@ pub trait WalletRead {
     /// tree size information for each block; or else the scan is likely to fail if notes belonging
     /// to the wallet are detected.
     ///
-    /// The returned range(s) may include block heights beyond the current chain tip.
+    /// The returned range(s) may include block heights beyond the current chain tip. Ranges are
+    /// returned in order of descending priority, and higher-priority ranges should always be
+    /// scanned before lower-priority ranges; in particular, ranges with [`ScanPriority::Verify`]
+    /// priority must always be scanned first in order to avoid blockchain continuity errors in the
+    /// case of a reorg.
     ///
     /// [`CompactBlock`]: crate::proto::compact_formats::CompactBlock
     fn suggest_scan_ranges(&self) -> Result<Vec<ScanRange>, Self::Error>;
@@ -452,6 +456,7 @@ pub struct ScannedBlock<Nf> {
 }
 
 impl<Nf> ScannedBlock<Nf> {
+    /// Constructs a new `ScannedBlock`
     pub fn from_parts(
         metadata: BlockMetadata,
         block_time: u32,
@@ -468,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, as a Unix timestamp in seconds.
     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
     }