From e10b4cf64f303930db4dc1fab9a353a562a453c5 Mon Sep 17 00:00:00 2001
From: Mark Pearce <mark.pearce@redspace.com>
Date: Thu, 23 Jul 2026 12:36:58 -0300
Subject: [PATCH 1/2] fix: normalize BrightScript hex literals in enum/const
 values

enumMember.getValue() and const literal tokens emit raw BrightScript
source text (e.g. &hFF0000FF), which isn't valid JS and crashes
jsdoc's parser for the whole file. Convert &hHEX to 0xHEX before
emitting.

Fixes #14
---
 CHANGELOG.md                            |  6 +++++
 src/convert-brighterscript-docs.spec.ts | 31 +++++++++++++++++++++++++
 src/convert-brighterscript-docs.ts      | 12 ++++++++--
 3 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1baf09a..2271e2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+-   Enum and const values containing BrightScript hex literals (`&hFF0000FF`) are now normalized to valid JS syntax (`0xFF0000FF`) before being emitted, instead of breaking jsdoc's parser ([#14](https://github.com/markwpearce/brighterscript-jsdocs-plugin/issues/14))
+
 ## [0.7.3]
 
 ### Fixed
diff --git a/src/convert-brighterscript-docs.spec.ts b/src/convert-brighterscript-docs.spec.ts
index 221f8e0..de1e111 100644
--- a/src/convert-brighterscript-docs.spec.ts
+++ b/src/convert-brighterscript-docs.spec.ts
@@ -382,6 +382,24 @@ describe('convertBrighterscriptDocs', () => {
                 };
             `);
         });
+
+        it('normalizes hex literals for enum member values', () => {
+            expectOutput(cbd.convertBrighterscriptDocs(`
+                enum Colors
+                    Black = &h000000FF
+                    White = &hFFFFFFFF
+                end enum
+            `), `
+                /**
+                 * @readonly
+                 * @enum
+                 */
+                var Colors = {
+                Black: 0x000000FF,
+                White: 0xFFFFFFFF,
+                };
+            `);
+        });
     });
 
     describe('interfaces', () => {
@@ -508,5 +526,18 @@ describe('convertBrighterscriptDocs', () => {
                     alpha.MY_CONSTANT = MY_CONSTANT;
             `);
         });
+
+        it('normalizes hex literals for constant values', () => {
+            expectOutput(cbd.convertBrighterscriptDocs(`
+                    const MY_CONSTANT = &hFF0000FF
+                `), `
+                    /**
+                     * @readonly
+                     * @constant
+                     * @default
+                     */
+                    var MY_CONSTANT = 0xFF0000FF;
+            `);
+        });
     });
 });
\ No newline at end of file
diff --git a/src/convert-brighterscript-docs.ts b/src/convert-brighterscript-docs.ts
index c87bb61..e9448ae 100644
--- a/src/convert-brighterscript-docs.ts
+++ b/src/convert-brighterscript-docs.ts
@@ -16,6 +16,14 @@ const escapeCharEntities = {
     '\'': '&apos;'
 };
 
+/**
+ * Converts BrightScript hex literal tokens (`&hFF`) to valid JS literal syntax (`0xFF`) so
+ * jsdoc's parser doesn't choke on the raw BrightScript source text.
+ */
+function normalizeBrightScriptNumericLiteral(value: string): string {
+    return value.replace(/&([Hh])([0-9A-Fa-f]+)/g, '0x$2');
+}
+
 
 interface PluginOptions {
     addModule?: boolean;
@@ -548,7 +556,7 @@ function processEnum(comment: bs.CommentStatement | undefined, enumStatement: bs
             output.push(...convertCommentTextToJsDocLines(enumMember), ' */');
             continue;
         }
-        output.push(`${enumMember.name}: ${enumMember.getValue()},`);
+        output.push(`${enumMember.name}: ${normalizeBrightScriptNumericLiteral(enumMember.getValue())},`);
     }
     output.push('};');
 
@@ -569,7 +577,7 @@ function processConst(comment: bs.CommentStatement | undefined, constStatement:
     output.push(...commentLines);
     let valueOutput = {};
     if (bs.isLiteralExpression(constStatement.value)) {
-        valueOutput = constStatement.value.token.text;
+        valueOutput = normalizeBrightScriptNumericLiteral(constStatement.value.token.text);
     }
     output.push(`var ${constStatement.name} = ${valueOutput};`);
 

From 54d90f75133a18ea04a1a3e75aee51adf4577471 Mon Sep 17 00:00:00 2001
From: Mark Pearce <mark.pearce@redspace.com>
Date: Thu, 23 Jul 2026 12:45:51 -0300
Subject: [PATCH 2/2] docs: add enum example with hex literal values

Exercises the &h hex literal normalization fix via npm run testdocs.
---
 examples/source/testEnum.bs | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/examples/source/testEnum.bs b/examples/source/testEnum.bs
index 799e4b7..19d7544 100644
--- a/examples/source/testEnum.bs
+++ b/examples/source/testEnum.bs
@@ -13,4 +13,11 @@ namespace Alpha
     East = 2
     West = 3
   end enum
-end namespace
\ No newline at end of file
+end namespace
+
+' ARGB colors, expressed as BrightScript hex literals
+enum ArgbColors
+  Black = &h000000FF
+  White = &hFFFFFFFF
+  TransparentRed = &hFF000080
+end enum
\ No newline at end of file