zcash_primitives: Improve ZIP 32 comments

zcash_primitives/src/sapling/zip32.rs

@@ -229,6 +229,11 @@ impl DiversifierKey {
     }
 }
 
+/// The derivation index associated with a key.
+///
+/// Master keys are never derived via the ZIP 32 child derivation process, but they have
+/// an index in their encoding. This type allows the encoding to be represented, while
+/// also enabling the derivation methods to only accept [`ChildIndex`].
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 enum KeyIndex {
     Master,
@@ -345,7 +350,7 @@ impl ExtendedSpendingKey {
         })
     }
 
-    /// Reads and decodes the encoded form of the extended spending key as define in
+    /// Reads and decodes the encoded form of the extended spending key as defined in
     /// [ZIP 32](https://zips.z.cash/zip-0032) from the provided reader.
     pub fn read<R: Read>(mut reader: R) -> io::Result<Self> {
         let depth = reader.read_u8()?;

zcash_primitives/src/zip32.rs

@@ -55,6 +55,9 @@ impl ConditionallySelectable for AccountId {
 pub struct ChildIndex(u32);
 
 impl ChildIndex {
+    /// Parses the given ZIP 32 child index.
+    ///
+    /// Returns `None` if the hardened bit is not set.
     pub fn from_index(i: u32) -> Option<Self> {
         if i >= (1 << 31) {
             Some(ChildIndex(i))
@@ -73,7 +76,7 @@ impl ChildIndex {
         Self(value + (1 << 31))
     }
 
-    /// Returns the index as an integer.
+    /// Returns the index as a 32-bit integer, including the hardened bit.
     pub fn index(&self) -> u32 {
         self.0
     }