From d2419fd740df4ef3db1e0a3832afb97fe9960071 Mon Sep 17 00:00:00 2001
From: Pollux <39353174+Pollux12@users.noreply.github.com>
Date: Tue, 18 Aug 2026 00:03:15 +0100
Subject: [PATCH] Add support for global flat enums

---
 __tests__/api-writer/glua-api-writer.spec.ts | 13 +++++++++----
 src/api-writer/glua-api-writer.ts            | 13 +++++++++----
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/__tests__/api-writer/glua-api-writer.spec.ts b/__tests__/api-writer/glua-api-writer.spec.ts
index 3bf768c..3f58d62 100644
--- a/__tests__/api-writer/glua-api-writer.spec.ts
+++ b/__tests__/api-writer/glua-api-writer.spec.ts
@@ -492,7 +492,7 @@ describe('GLua API Writer', () => {
     expect(api).toContain('---@field GetEntityDriveMode function');
   });
 
-  it('should create aliasses for global enumerations', () => {
+  it('should create flat enums for global enumerations', () => {
     const writer = new GluaApiWriter();
     const api = writer.writePage(<Enum>{
       type: 'enum',
@@ -527,9 +527,14 @@ describe('GLua API Writer', () => {
     expect(api).toContain('---@readonly\nMATERIAL_FOG_NONE = 0');
     expect(api).toContain('---@readonly\nMATERIAL_FOG_LINEAR = 1');
     expect(api).toContain('---@readonly\nMATERIAL_FOG_LINEAR_BELOW_FOG_Z = -2147483648');
-    expect(api).toContain('---@alias MATERIAL_FOG');
-    expect(api).toContain('---| number # Raw numeric enum value');
-    expect(api).toContain('---| 0 # MATERIAL_FOG_NONE');
+    expect(api).toContain('---@enum MATERIAL_FOG : number');
+    expect(api).toContain('---| MATERIAL_FOG_NONE # No fog');
+    expect(api).toContain('---| MATERIAL_FOG_LINEAR # Linear fog');
+    // A member without a wiki description carries no detail.
+    expect(api).toContain('---| MATERIAL_FOG_LINEAR_BELOW_FOG_Z\n');
+    // TODO values are skipped, and the enum no longer widens to bare `number`.
+    expect(api).not.toContain('MATERIAL_FOG_NEW_FAKE');
+    expect(api).not.toContain('---@alias MATERIAL_FOG');
   });
 
   it('should create enums for table enumerations', () => {
diff --git a/src/api-writer/glua-api-writer.ts b/src/api-writer/glua-api-writer.ts
index 9577001..7eb944c 100644
--- a/src/api-writer/glua-api-writer.ts
+++ b/src/api-writer/glua-api-writer.ts
@@ -466,13 +466,18 @@ export class GluaApiWriter {
         const enumAliasValue = literalUnion.length > 0 ? `${literalUnion} | number` : 'number';
         api += `--- @alias ${_enum.name} ${enumAliasValue}\n`;
       } else {
-        // Advanced annotation: emit numeric literals to help literal-type inference for enum-backed numbers.
-        api += `\n---@alias ${_enum.name}\n`;
-        api += '---| number # Raw numeric enum value\n';
+        // Garry's Mod enums are flat globals, so the field list names each constant.
+        // Completion then offers `EF_BONEMERGE` rather than the raw value it holds.
+        // The `: number` base keeps bitwise combinations such as `bit.bor(EF_A, EF_B)`
+        // assignable, which the previous `---| number` alias member allowed.
+        api += `\n---@enum ${_enum.name} : number\n`;
 
         for (const item of _enum.items) {
           if (item.key !== '' && !isNaN(Number(item.value.trim()))) {
-            api += `---| ${item.value} # ${item.key}\n`;
+            const description = item.description?.trim()
+              ? ` # ${removeNewlines(item.description)}`
+              : '';
+            api += `---| ${item.key}${description}\n`;
           }
         }
       }