borrow_tracker: update comments regarding protectors

Author: RalfJung

src/tools/miri/src/borrow_tracker/mod.rs

@@ -96,7 +96,6 @@ pub struct GlobalStateInner {
     /// Next unused call ID (for protectors).
     next_call_id: CallId,
     /// All currently protected tags.
-    /// An item is protected if its tag is in this set, *and* it has the "protected" bit set.
     /// We add tags to this when they are created with a protector in `reborrow`, and
     /// we remove tags from this when the call which is protecting them returns, in
     /// `GlobalStateInner::end_call`. See `Stack::item_invalidated` for more details.

src/tools/miri/src/borrow_tracker/stacked_borrows/item.rs

@@ -7,9 +7,12 @@ use crate::borrow_tracker::BorTag;
 pub struct Item(u64);
 
 // An Item contains 3 bitfields:
-// * Bits 0-61 store a BorTag
-// * Bits 61-63 store a Permission
-// * Bit 64 stores a flag which indicates if we have a protector
+// * Bits 0-61 store a BorTag.
+// * Bits 61-63 store a Permission.
+// * Bit 64 stores a flag which indicates if we might have a protector.
+//   This is purely an optimization: if the bit is set, the tag *might* be
+//   in `protected_tags`, but if the bit is not set then the tag is definitely
+//   not in `protected_tags`.
 const TAG_MASK: u64 = u64::MAX >> 3;
 const PERM_MASK: u64 = 0x3 << 61;
 const PROTECTED_MASK: u64 = 0x1 << 63;