better code docs

noir-projects/aztec-nr/aztec/src/state_vars/public_immutable.nr

@@ -74,6 +74,8 @@ where
     // Note that we don't access the context, but we do call oracles that are only available in public
     // docs:start:public_immutable_struct_read
     pub fn read(self) -> T {
+        // Unlike in private in public we just load the value without any kind of verification against the packed hash
+        // as in public there is no notion of unconstrained and hence no optimization to be made.
         self.context.storage_read(self.storage_slot)
     }
     // docs:end:public_immutable_struct_read
@@ -92,6 +94,11 @@ impl<T, let T_PACKED_LEN: u32> PublicImmutable<T, &mut PrivateContext>
 where
     T: Packable<T_PACKED_LEN>,
 {
+    /// Reads an immutable value from public storage in private.
+    ///
+    /// Optimizes number of merkle proofs performed by reading the data in an unconstrained context and its hash
+    /// in constrained context and checking the data against the hash. This results in significant gate count savings
+    /// for values occupying more than 1 storage slot.
     pub fn read(self) -> T {
         let header = self.context.get_block_header();
         let contract_address = (*self.context).this_address();