From 9b9d02078cb937013bcb686e44b855a9ee4db196 Mon Sep 17 00:00:00 2001
From: Boshen <1430279+Boshen@users.noreply.github.com>
Date: Wed, 20 Nov 2024 09:18:25 +0000
Subject: [PATCH] docs(semantic): document the meaning of
 `ReferenceFlags::Read` and `Write` (#7368)

closes #5165
---
 crates/oxc_syntax/src/reference.rs | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/crates/oxc_syntax/src/reference.rs b/crates/oxc_syntax/src/reference.rs
index 67d4df85cbbda..1f80be1953002 100644
--- a/crates/oxc_syntax/src/reference.rs
+++ b/crates/oxc_syntax/src/reference.rs
@@ -76,9 +76,31 @@ bitflags! {
     #[cfg_attr(feature = "serialize", derive(Serialize))]
     pub struct ReferenceFlags: u8 {
         const None = 0;
-        /// A symbol is being read as a Value
+        /// A symbol is being read as a Value.
+        ///
+        /// This value can be derived from the spec:
+        ///
+        /// Under `Runtime Semantics: Evaluation`, when [`GetValue`](https://tc39.es/ecma262/#sec-getvalue) is called
+        /// on a expression, and the expression is an `IdentifierReference`.
+        ///
+        /// For example:
+        /// ```text
+        /// 1. Let lRef be ? Evaluation of Expression.
+        /// 2. Perform ? GetValue(lRef).
+        /// ```
         const Read = 1 << 0;
         /// A symbol is being written to in a Value context.
+        ///
+        /// This value can be derived from the spec:
+        ///
+        /// Under `Runtime Semantics: Evaluation`, when [`PutValue`](https://tc39.es/ecma262/#sec-putvalue) is called
+        /// on a expression, and the expression is an `IdentifierReference`.
+        ///
+        /// For example:
+        /// ```text
+        /// 1. Let lhs be ? Evaluation of LeftHandSideExpression.
+        /// 2. Perform ? PutValue(lhs, newValue).
+        /// ```
         const Write = 1 << 1;
         /// Used in type definitions.
         const Type = 1 << 2;