tweak docs

Author: newpavlov

block-buffer/src/lib.rs

@@ -189,9 +189,9 @@ impl<BS: BlockSizes, K: BufferKind> BlockBuffer<BS, K> {
             let buf = &mut g.0.buffer;
             // SAFETY: length of `left` is equal to number of remaining bytes in `buffer`,
             // so we can copy data into it and process `buffer` as fully initialized block.
-            // Note that we may temporarily break the invariant, but we reset the buffer
-            // immediately after `compress` using `Drop` impl of `ResetGuard`, so this code
-            // is safe even if `compress` panics.
+            // Note that this code can temporarily break the eager buffer invariant,
+            // but we reset the buffer immediately after `compress` using `Drop` impl of
+            // `ResetGuard`, so this code is safe even if `compress` panics.
             let block = unsafe {
                 let buf_ptr = buf.as_mut_ptr().cast::<u8>().add(pos);
                 ptr::copy_nonoverlapping(left.as_ptr(), buf_ptr, left.len());

block-buffer/src/read.rs

@@ -113,6 +113,9 @@ impl<BS: BlockSizes> ReadBuffer<BS> {
         let g = ResetGuard(self);
         let buf = &mut g.0.buffer;
 
+        // Note that generated block is likely to break the `ReadBuffer` invariant.
+        // We restore it using `set_pos_unchecked` below and in case if one of the closures
+        // panic the buffer gets reset by the guard.
         gen_block(buf);
         read_fn(&buf[..read_len]);