docs(parser): improve docs for Token::read_bool

crates/oxc_parser/src/lexer/token.rs

@@ -193,35 +193,38 @@ impl Token {
 
     /// Read `bool` from 8 bits starting at bit position `shift`.
     ///
+    /// # SAFETY
+    ///
+    /// `shift` must be the location of a valid boolean "field" in [`Token`]
+    /// e.g. `ESCAPED_SHIFT`. The caller must guarantee that the 8 bits at
+    /// `shift` contain only 0 or 1, making it safe to read as a `bool`.
+    ///
+    /// # Performance analysis
+    ///
     /// This method uses unsafe pointer arithmetic to directly read a boolean value
     /// from the token's 128-bit representation. This approach is deliberately chosen
     /// for performance optimization on hot paths.
     ///
-    /// # Performance Analysis
-    ///
-    /// This unsafe pointer arithmetic approach generates only 3 CPU instructions:
+    /// This unsafe pointer arithmetic approach generates only 1 CPU instruction:
     /// ```asm
-    /// movzx   eax, BYTE PTR [rdi+9]  ; Load byte at offset
-    /// and     eax, 1                  ; Mask to get boolean
-    /// ret                             ; Return
+    /// movzx   eax, byte ptr [rdi + 9]  ; Load byte at offset
+    /// ```
+    ///
+    /// Compared to the safe bit-shift alternative:
+    /// ```ignore
+    /// (token.0 >> shift) & 1 != 0
     /// ```
     ///
-    /// Compared to the safe bit-shift alternative which generates 4 instructions:
     /// ```asm
-    /// mov     rax, QWORD PTR [rdi+8]  ; Load 64-bit value
-    /// shr     rax, 8                  ; Shift to extract bit
-    /// and     eax, 1                  ; Mask to get boolean
-    /// ret                             ; Return
+    /// movzx   eax, byte ptr [rdi + 9]  ; Load byte at offset
+    /// and     al, 1                    ; Mask to lower bit only
     /// ```
     ///
+    /// <https://godbolt.org/z/7xxrP348P>
+    ///
     /// This optimization was retained after careful benchmarking (see PR #13788),
     /// where the single instruction difference on hot paths justified keeping
     /// the unsafe implementation.
-    ///
-    /// # SAFETY
-    /// `shift` must be the location of a valid boolean "field" in [`Token`]
-    /// e.g. `ESCAPED_SHIFT`. The caller must guarantee that the 8 bits at
-    /// `shift` contain only 0 or 1, making it safe to read as a `bool`.
     #[expect(clippy::inline_always)]
     #[inline(always)] // So `shift` is statically known
     unsafe fn read_bool(&self, shift: usize) -> bool {