From 4694f194a64cd251ac817a289135d58c1bed7214 Mon Sep 17 00:00:00 2001
From: Mark Pearce <mark.pearce@redspace.com>
Date: Thu, 23 Jul 2026 12:28:49 -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                            |  4 ++++
 src/convert-brighterscript-docs.spec.ts | 31 +++++++++++++++++++++++++
 src/convert-brighterscript-docs.ts      | 12 ++++++++--
 3 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4b69d34..9baa5fd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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))
+
 ### Added
 
 -   Support for BrighterScript v1 type syntax in doc comments: union types (`string or integer` → `{(string|integer)}`), typed arrays (`string[]` → `{Array.<string>}`, including arrays of custom class/interface types), and intersection types (`A and B`, which fall back to `{dynamic}` since JSDoc's type grammar has no intersection operator)
diff --git a/src/convert-brighterscript-docs.spec.ts b/src/convert-brighterscript-docs.spec.ts
index 3469d38..9fe88bf 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,6 +526,19 @@ 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;
+            `);
+        });
     });
 
     describe('comment adjacency', () => {
diff --git a/src/convert-brighterscript-docs.ts b/src/convert-brighterscript-docs.ts
index 11b2146..dd34dff 100644
--- a/src/convert-brighterscript-docs.ts
+++ b/src/convert-brighterscript-docs.ts
@@ -18,6 +18,14 @@ const escapeCharEntities = {
 
 const typeGetOptions: bs.GetTypeOptions = { flags: bs.SymbolTypeFlag.typetime };
 
+/**
+ * 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;
@@ -555,7 +563,7 @@ function processEnum(enumStatement: bs.EnumStatement, moduleName = '', namespace
         if (memberCommentLines.length) {
             output.push(...convertCommentTextToJsDocLines(memberCommentLines), ' */');
         }
-        output.push(`${enumMember.name}: ${enumMember.getValue()},`);
+        output.push(`${enumMember.name}: ${normalizeBrightScriptNumericLiteral(enumMember.getValue())},`);
     }
     output.push('};');
 
@@ -576,7 +584,7 @@ function processConst(constStatement: bs.ConstStatement, moduleName = '', namesp
     output.push(...commentLines);
     let valueOutput = {};
     if (bs.isLiteralExpression(constStatement.value)) {
-        valueOutput = constStatement.value.tokens.value.text;
+        valueOutput = normalizeBrightScriptNumericLiteral(constStatement.value.tokens.value.text);
     }
     output.push(`var ${constStatement.name} = ${valueOutput};`);
 

From 89f49618fccb67fc66210599df20b47e55712063 Mon Sep 17 00:00:00 2001
From: Mark Pearce <mark.pearce@redspace.com>
Date: Thu, 23 Jul 2026 12:45:24 -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