From e4aa5b51c146feff0de4db24c48fc9db40ede74b Mon Sep 17 00:00:00 2001
From: overlookmotel <557937+overlookmotel@users.noreply.github.com>
Date: Thu, 12 Mar 2026 12:46:02 +0000
Subject: [PATCH] docs(parser/napi, linter/plugins): add JSDoc comments to raw
 transfer constants (#20286)

Comments-only change. Add JSDoc comments to the constants related to raw transfer in generated files `constants.js` / `constants.ts`. There are now a lot of constants, and it wasn't clear what they all mean.
---
 apps/oxlint/src-js/generated/constants.ts     | 47 +++++++++++++++++++
 napi/parser/src-js/generated/constants.js     | 47 +++++++++++++++++++
 .../ast_tools/src/generators/raw_transfer.rs  | 47 +++++++++++++++++++
 3 files changed, 141 insertions(+)

diff --git a/apps/oxlint/src-js/generated/constants.ts b/apps/oxlint/src-js/generated/constants.ts
index 84a8e526ef244..4b57d05c5180a 100644
--- a/apps/oxlint/src-js/generated/constants.ts
+++ b/apps/oxlint/src-js/generated/constants.ts
@@ -1,15 +1,62 @@
 // Auto-generated code, DO NOT EDIT DIRECTLY!
 // To edit this generated file you have to edit `tasks/ast_tools/src/generators/raw_transfer.rs`.
 
+/**
+ * Total size of the transfer buffer in bytes (block size minus allocator metadata).
+ */
 export const BUFFER_SIZE = 2147483616;
+
+/**
+ * Required alignment of the transfer buffer (4 GiB).
+ */
 export const BUFFER_ALIGN = 4294967296;
+
+/**
+ * Size of the active data area in bytes (buffer size minus raw metadata and chunk footer).
+ */
 export const ACTIVE_SIZE = 2147483552;
+
+/**
+ * Byte offset of the data pointer within the buffer, divided by 4 (for `Uint32Array` indexing).
+ */
 export const DATA_POINTER_POS_32 = 536870900;
+
+/**
+ * Byte offset of the `is_ts` flag within the buffer.
+ */
 export const IS_TS_FLAG_POS = 2147483612;
+
+/**
+ * Byte offset of the `is_jsx` flag within the buffer.
+ */
 export const IS_JSX_FLAG_POS = 2147483613;
+
+/**
+ * Byte offset of the `has_bom` flag within the buffer.
+ */
 export const HAS_BOM_FLAG_POS = 2147483614;
+
+/**
+ * Byte offset of the tokens offset within the buffer, divided by 4 (for `Uint32Array` indexing).
+ */
 export const TOKENS_OFFSET_POS_32 = 536870901;
+
+/**
+ * Byte offset of the tokens length within the buffer, divided by 4 (for `Uint32Array` indexing).
+ */
 export const TOKENS_LEN_POS_32 = 536870902;
+
+/**
+ * Byte offset of the `program` field, relative to start of `RawTransferData`.
+ */
 export const PROGRAM_OFFSET = 0;
+
+/**
+ * Byte offset of pointer to start of source text, relative to start of `Program`.
+ */
 export const SOURCE_START_OFFSET = 8;
+
+/**
+ * Byte offset of length of source text, relative to start of `Program`.
+ */
 export const SOURCE_LEN_OFFSET = 16;
diff --git a/napi/parser/src-js/generated/constants.js b/napi/parser/src-js/generated/constants.js
index 84a8e526ef244..4b57d05c5180a 100644
--- a/napi/parser/src-js/generated/constants.js
+++ b/napi/parser/src-js/generated/constants.js
@@ -1,15 +1,62 @@
 // Auto-generated code, DO NOT EDIT DIRECTLY!
 // To edit this generated file you have to edit `tasks/ast_tools/src/generators/raw_transfer.rs`.
 
+/**
+ * Total size of the transfer buffer in bytes (block size minus allocator metadata).
+ */
 export const BUFFER_SIZE = 2147483616;
+
+/**
+ * Required alignment of the transfer buffer (4 GiB).
+ */
 export const BUFFER_ALIGN = 4294967296;
+
+/**
+ * Size of the active data area in bytes (buffer size minus raw metadata and chunk footer).
+ */
 export const ACTIVE_SIZE = 2147483552;
+
+/**
+ * Byte offset of the data pointer within the buffer, divided by 4 (for `Uint32Array` indexing).
+ */
 export const DATA_POINTER_POS_32 = 536870900;
+
+/**
+ * Byte offset of the `is_ts` flag within the buffer.
+ */
 export const IS_TS_FLAG_POS = 2147483612;
+
+/**
+ * Byte offset of the `is_jsx` flag within the buffer.
+ */
 export const IS_JSX_FLAG_POS = 2147483613;
+
+/**
+ * Byte offset of the `has_bom` flag within the buffer.
+ */
 export const HAS_BOM_FLAG_POS = 2147483614;
+
+/**
+ * Byte offset of the tokens offset within the buffer, divided by 4 (for `Uint32Array` indexing).
+ */
 export const TOKENS_OFFSET_POS_32 = 536870901;
+
+/**
+ * Byte offset of the tokens length within the buffer, divided by 4 (for `Uint32Array` indexing).
+ */
 export const TOKENS_LEN_POS_32 = 536870902;
+
+/**
+ * Byte offset of the `program` field, relative to start of `RawTransferData`.
+ */
 export const PROGRAM_OFFSET = 0;
+
+/**
+ * Byte offset of pointer to start of source text, relative to start of `Program`.
+ */
 export const SOURCE_START_OFFSET = 8;
+
+/**
+ * Byte offset of length of source text, relative to start of `Program`.
+ */
 export const SOURCE_LEN_OFFSET = 16;
diff --git a/tasks/ast_tools/src/generators/raw_transfer.rs b/tasks/ast_tools/src/generators/raw_transfer.rs
index 8b05b90f74d0e..e21480f08b48d 100644
--- a/tasks/ast_tools/src/generators/raw_transfer.rs
+++ b/tasks/ast_tools/src/generators/raw_transfer.rs
@@ -1343,17 +1343,64 @@ fn generate_constants(consts: Constants) -> (String, TokenStream) {
 
     #[rustfmt::skip]
     let js_output = format!("
+        /**
+         * Total size of the transfer buffer in bytes (block size minus allocator metadata).
+         */
         export const BUFFER_SIZE = {buffer_size};
+
+        /**
+         * Required alignment of the transfer buffer (4 GiB).
+         */
         export const BUFFER_ALIGN = {BLOCK_ALIGN};
+
+        /**
+         * Size of the active data area in bytes (buffer size minus raw metadata and chunk footer).
+         */
         export const ACTIVE_SIZE = {active_size};
+
+        /**
+         * Byte offset of the data pointer within the buffer, divided by 4 (for `Uint32Array` indexing).
+         */
         export const DATA_POINTER_POS_32 = {data_pointer_pos_32};
+
+        /**
+         * Byte offset of the `is_ts` flag within the buffer.
+         */
         export const IS_TS_FLAG_POS = {is_ts_pos};
+
+        /**
+         * Byte offset of the `is_jsx` flag within the buffer.
+         */
         export const IS_JSX_FLAG_POS = {is_jsx_pos};
+
+        /**
+         * Byte offset of the `has_bom` flag within the buffer.
+         */
         export const HAS_BOM_FLAG_POS = {has_bom_pos};
+
+        /**
+         * Byte offset of the tokens offset within the buffer, divided by 4 (for `Uint32Array` indexing).
+         */
         export const TOKENS_OFFSET_POS_32 = {tokens_offset_pos_32};
+
+        /**
+         * Byte offset of the tokens length within the buffer, divided by 4 (for `Uint32Array` indexing).
+         */
         export const TOKENS_LEN_POS_32 = {tokens_len_pos_32};
+
+        /**
+         * Byte offset of the `program` field, relative to start of `RawTransferData`.
+         */
         export const PROGRAM_OFFSET = {program_offset};
+
+        /**
+         * Byte offset of pointer to start of source text, relative to start of `Program`.
+         */
         export const SOURCE_START_OFFSET = {source_start_offset};
+
+        /**
+         * Byte offset of length of source text, relative to start of `Program`.
+         */
         export const SOURCE_LEN_OFFSET = {source_len_offset};
     ");