From f4db3e22469df89b6b3aaf82864c1fb4c4abccbc Mon Sep 17 00:00:00 2001
From: overlookmotel <theoverlookmotel@gmail.com>
Date: Thu, 21 Nov 2024 10:48:38 +0000
Subject: [PATCH] docs(syntax): more comments for `ReferenceFlags`

---
 crates/oxc_syntax/src/reference.rs | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/crates/oxc_syntax/src/reference.rs b/crates/oxc_syntax/src/reference.rs
index 1f80be19530028..86e3caa238f0a2 100644
--- a/crates/oxc_syntax/src/reference.rs
+++ b/crates/oxc_syntax/src/reference.rs
@@ -53,6 +53,14 @@ bitflags! {
     /// 2. Types being referenced as types
     /// 3. Values being used in type contexts
     ///
+    /// ## Values
+    /// Whether a reference is considered [`Read`] or [`Write`] is determined according to ECMA spec.
+    ///
+    /// See comments on [`Read`] and [`Write`] below.
+    ///
+    /// See <https://github.com/oxc-project/oxc/issues/5165#issuecomment-2488333549> for a runtime test
+    /// to determine Read/Write operations in a code snippet.
+    ///
     /// ## Value as Type
     /// The [`ValueAsType`] flag is a temporary marker for references that need to
     /// resolve to value symbols initially, but will ultimately be treated as type references.
@@ -76,12 +84,12 @@ bitflags! {
     #[cfg_attr(feature = "serialize", derive(Serialize))]
     pub struct ReferenceFlags: u8 {
         const None = 0;
-        /// A symbol is being read as a Value.
+        /// Symbol is being read from as a Value.
         ///
-        /// This value can be derived from the spec:
+        /// Whether a reference is `Read` is as defined in 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`.
+        /// 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
@@ -89,12 +97,12 @@ bitflags! {
         /// 2. Perform ? GetValue(lRef).
         /// ```
         const Read = 1 << 0;
-        /// A symbol is being written to in a Value context.
+        /// Symbol is being written to as a Value.
         ///
-        /// This value can be derived from the spec:
+        /// Whether a reference is `Write` is as defined in 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`.
+        /// 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
@@ -109,7 +117,7 @@ bitflags! {
         /// The symbol being referenced is a value.
         ///
         /// Note that this does not necessarily indicate the reference is used
-        /// in a value context, since type queries are also flagged as [`Read`]
+        /// in a value context, since type queries are also flagged as [`Read`].
         ///
         /// [`Read`]: ReferenceFlags::Read
         const Value = Self::Read.bits() | Self::Write.bits();