better explain the handle packing code

Author: beepster4096

src/shims/windows/handle.rs

@@ -30,9 +30,9 @@ impl RealHandle {
     }
 
     fn packed_disc_size() -> u32 {
-        (variant_count::<Self>().log2() + 1)
-            .try_into()
-            .expect("this would require more than 2^4294967294 variants to overflow")
+        // log2(x) + 1 is how many bits it takes to store x
+        // because the discriminants start at 1, the variant count is equal to the highest discriminant
+        variant_count::<Self>().log2() + 1
     }
 
     /// This function packs the discriminant and data values into a 31-bit space.
@@ -45,10 +45,14 @@ impl RealHandle {
         let discriminant = self.discriminant();
         let data = self.data();
 
-        // these assertions ensure the components avoid overlapping eachother and the sign bit
+        // make sure the discriminant fits into `disc_size` bits
         assert!(discriminant < 2u32.pow(disc_size));
+
+        // make sure the data fits into `data_size` bits
         assert!(data < 2u32.pow(data_size));
 
+        // packs the data into the lower `data_size` bits
+        // and packs the discriminant right above the data
         (discriminant << data_size | data) as i32
     }
 
@@ -69,7 +73,10 @@ impl RealHandle {
         // the lower `data_size` bits of this mask are 1
         let data_mask = 2u32.pow(data_size) - 1;
 
+        // the discriminant is stored right above the lower `data_size` bits
         let discriminant = handle_bits >> data_size;
+
+        // the data is stored in the lower `data_size` bits
         let data = handle_bits & data_mask;
 
         Self::new(discriminant, data)