Skip to content

Commit ed4896e

Browse files
luttjeluttje
authored
Merge pull request #16 from aske02/feature/deprecated-annotation
Feature/deprecated annotation
2 parents 70b65cb + 18d10eb commit ed4896e

File tree

9 files changed

+174
-45
lines changed

9 files changed

+174
-45
lines changed

‎__tests__/test-data/offline-sites/gmod-wiki/struct-custom-entity-fields.ts

Lines changed: 71 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -46,25 +46,77 @@ This can also be set from map, see <page>Sandbox Specific Mapping</page></item>
4646
4747
</structure>`;
4848

49-
export const apiDefinition = `---@class Custom_Entity_Fields
50-
---@field GetEntityDriveMode function \`Serverside\`, Sandbox and Sandbox derived only. Called by the Drive property to override the default drive type, which is \`drive_sandbox\`.
51-
---@field OnEntityCopyTableFinish function Documented at ENTITY:OnEntityCopyTableFinish.
52-
---@field PostEntityCopy function Documented at ENTITY:PostEntityCopy.
53-
---@field PostEntityPaste function Documented at ENTITY:PostEntityPaste.
54-
---@field PreEntityCopy function Documented at ENTITY:PreEntityCopy.
55-
---@field OnDuplicated function Documented at ENTITY:OnDuplicated.
56-
---@field PhysgunDisabled boolean \`Shared\`, Sandbox or Sandbox derived only. If set to \`true\`, physgun will not be able to pick this entity up. This can also be set from map, see Sandbox Specific Mapping
57-
---@field PhysgunPickup function \`Shared\`, Sandbox or Sandbox derived only. Called from GM:PhysgunPickup, overrides \`PhysgunDisabled\`
58-
---@field m_tblToolsAllowed table \`Shared\`, Sandbox or Sandbox derived only. Controls which tools **and** properties can be used on this entity. Format is a list of strings where each string is the tool or property classname. This can also be set from map, see Sandbox Specific Mapping
59-
---@field GravGunPickupAllowed function Documented at ENTITY:GravGunPickupAllowed.
60-
---@field GravGunPunt function Documented at ENTITY:GravGunPunt.
61-
---@field CanProperty function Documented at ENTITY:CanProperty.
62-
---@field CanTool function Documented at ENTITY:CanTool.
63-
---@field CalcAbsolutePosition function Documented at ENTITY:CalcAbsolutePosition.
64-
---@field RenderOverride function Documented at ENTITY:RenderOverride.
65-
---@field m_RenderOrigin Vector (Clientside) Do not use.
66-
---@field m_RenderAngles Angle (Clientside) Do not use.
67-
local Custom_Entity_Fields = {}\n\n`;
49+
export const apiDefinition =
50+
`---@class Custom_Entity_Fields
51+
local Custom_Entity_Fields = {}
52+
53+
---\`Serverside\`, Sandbox and Sandbox derived only. Called by the Drive property to override the default drive type, which is \`drive_sandbox\`.
54+
---@type function
55+
Custom_Entity_Fields.GetEntityDriveMode = nil
56+
57+
---Documented at ENTITY:OnEntityCopyTableFinish.
58+
---@type function
59+
Custom_Entity_Fields.OnEntityCopyTableFinish = nil
60+
61+
---Documented at ENTITY:PostEntityCopy.
62+
---@type function
63+
Custom_Entity_Fields.PostEntityCopy = nil
64+
65+
---Documented at ENTITY:PostEntityPaste.
66+
---@type function
67+
Custom_Entity_Fields.PostEntityPaste = nil
68+
69+
---Documented at ENTITY:PreEntityCopy.
70+
---@type function
71+
Custom_Entity_Fields.PreEntityCopy = nil
72+
73+
---Documented at ENTITY:OnDuplicated.
74+
---@type function
75+
Custom_Entity_Fields.OnDuplicated = nil
76+
77+
---\`Shared\`, Sandbox or Sandbox derived only. If set to \`true\`, physgun will not be able to pick this entity up. This can also be set from map, see Sandbox Specific Mapping
78+
---@type boolean
79+
Custom_Entity_Fields.PhysgunDisabled = nil
80+
81+
---\`Shared\`, Sandbox or Sandbox derived only. Called from GM:PhysgunPickup, overrides \`PhysgunDisabled\`
82+
---@type function
83+
Custom_Entity_Fields.PhysgunPickup = nil
84+
85+
---\`Shared\`, Sandbox or Sandbox derived only. Controls which tools **and** properties can be used on this entity. Format is a list of strings where each string is the tool or property classname. This can also be set from map, see Sandbox Specific Mapping
86+
---@type table
87+
Custom_Entity_Fields.m_tblToolsAllowed = nil
88+
89+
---Documented at ENTITY:GravGunPickupAllowed.
90+
---@type function
91+
Custom_Entity_Fields.GravGunPickupAllowed = nil
92+
93+
---Documented at ENTITY:GravGunPunt.
94+
---@type function
95+
Custom_Entity_Fields.GravGunPunt = nil
96+
97+
---Documented at ENTITY:CanProperty.
98+
---@type function
99+
Custom_Entity_Fields.CanProperty = nil
100+
101+
---Documented at ENTITY:CanTool.
102+
---@type function
103+
Custom_Entity_Fields.CanTool = nil
104+
105+
---Documented at ENTITY:CalcAbsolutePosition.
106+
---@type function
107+
Custom_Entity_Fields.CalcAbsolutePosition = nil
108+
109+
---Documented at ENTITY:RenderOverride.
110+
---@type function
111+
Custom_Entity_Fields.RenderOverride = nil
112+
113+
---(Clientside) Do not use.
114+
---@type Vector
115+
Custom_Entity_Fields.m_RenderOrigin = nil
116+
117+
---(Clientside) Do not use.
118+
---@type Angle
119+
Custom_Entity_Fields.m_RenderAngles = nil\n\n`;
68120

69121
export const json = {
70122
name: 'Custom_Entity_Fields',

‎custom/class.Color.lua

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@
33
---@field g number The green component of the color.
44
---@field b number The blue component of the color.
55
---@field a number The alpha component of the color.
6-
---{{CLASS_FIELDS}}
76
local Color = {}
7+
8+
---{{CLASS_FIELDS}}

‎custom/class.ENT.lua

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
---@class ENT : Entity
2-
---{{CLASS_FIELDS}}
32
ENT = {}
3+
4+
---{{CLASS_FIELDS}}

‎custom/class.NPC.lua

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
---@class NPC : Entity
2-
---{{CLASS_FIELDS}}
32
local NPC = {}
3+
4+
---{{CLASS_FIELDS}}

‎custom/class.Player.lua

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
---@class Player : Entity
2-
---{{CLASS_FIELDS}}
32
local Player = {}
3+
4+
---{{CLASS_FIELDS}}

‎custom/class.SWEP.lua

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
---@class SWEP : WEAPON
2-
---{{CLASS_FIELDS}}
32
SWEP = {}
3+
4+
---{{CLASS_FIELDS}}

‎src/api-writer/glua-api-writer.ts

Lines changed: 47 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { ClassFunction, Enum, Function, HookFunction, LibraryFunction, Panel, PanelFunction, Realm, Struct, WikiPage, isPanel } from '../scrapers/wiki-page-markup-scraper.js';
2-
import { putCommentBeforeEachLine, removeNewlines, safeFileName, toLowerCamelCase } from '../utils/string.js';
2+
import { escapeSingleQuotes, putCommentBeforeEachLine, removeNewlines, safeFileName, toLowerCamelCase } from '../utils/string.js';
33
import {
44
isClassFunction,
55
isHookFunction,
@@ -69,12 +69,12 @@ export class GluaApiWriter {
6969
const fileSafeAddress = safeFileName(page.address, '.');
7070
if (this.pageOverrides.has(fileSafeAddress)) {
7171
let api = '';
72-
72+
7373
if (isClassFunction(page))
74-
api += this.writeClass(page.parent);
74+
api += this.writeClass(page.parent, undefined, undefined, page.deprecated);
7575
else if (isLibraryFunction(page))
7676
api += this.writeLibraryGlobal(page);
77-
77+
7878
api += this.pageOverrides.get(fileSafeAddress);
7979

8080
return `${api}\n\n`;
@@ -94,23 +94,26 @@ export class GluaApiWriter {
9494
return this.writeStruct(page);
9595
}
9696

97-
private writeClass(className: string, parent?: string, classFields: string = '') {
97+
private writeClass(className: string, parent?: string, classFields: string = '', deprecated?: string ) {
9898
let api: string = '';
9999

100100
if (!this.writtenClasses.has(className)) {
101101
const classOverride = `class.${className}`;
102102
if (this.pageOverrides.has(classOverride)) {
103103
api += this.pageOverrides.get(classOverride)!.replace(/\n$/g, '') + '\n\n';
104-
api = api.replace('---{{CLASS_FIELDS}}\n', classFields);
104+
api = api.replace('---{{CLASS_FIELDS}}', classFields);
105105
} else {
106+
if (deprecated)
107+
api += `---@deprecated ${deprecated ?? ''}\n`
108+
106109
api += `---@class ${className}`;
107110

108111
if (parent)
109112
api += ` : ${parent}`;
110113

111114
api += '\n';
112-
api += classFields;
113115
api += `local ${className} = {}\n\n`;
116+
api += classFields;
114117
}
115118

116119
this.writtenClasses.add(className);
@@ -121,7 +124,12 @@ export class GluaApiWriter {
121124

122125
private writeLibraryGlobal(func: LibraryFunction) {
123126
if (!func.dontDefineParent && !this.writtenLibraryGlobals.has(func.parent)) {
124-
const global = `${func.parent} = {}\n\n`;
127+
let global = '';
128+
129+
if(func.deprecated)
130+
global += `---@deprecated ${func.deprecated ?? ''}\n`;
131+
132+
global += `${func.parent} = {}\n\n`;
125133

126134
this.writtenLibraryGlobals.add(func.parent);
127135

@@ -132,7 +140,7 @@ export class GluaApiWriter {
132140
}
133141

134142
private writeClassFunction(func: ClassFunction) {
135-
let api: string = this.writeClass(func.parent);
143+
let api: string = this.writeClass(func.parent, undefined, undefined, func.deprecated);
136144

137145
api += this.writeFunctionLuaDocComment(func, func.realm);
138146
api += this.writeFunctionDeclaration(func, func.realm, ':');
@@ -154,7 +162,7 @@ export class GluaApiWriter {
154162
}
155163

156164
private writePanel(panel: Panel) {
157-
return this.writeClass(panel.name, panel.parent);
165+
return this.writeClass(panel.name, panel.parent, undefined, panel.deprecated);
158166
}
159167

160168
private writePanelFunction(func: PanelFunction) {
@@ -170,6 +178,9 @@ export class GluaApiWriter {
170178
let api: string = '';
171179
const isContainedInTable = _enum.items[0]?.key.includes('.') ?? false;
172180

181+
if (_enum.deprecated)
182+
api += `---@deprecated ${_enum.deprecated ?? ''}\n`;
183+
173184
api += `---@enum ${_enum.name}\n`;
174185

175186
if (isContainedInTable)
@@ -180,8 +191,10 @@ export class GluaApiWriter {
180191
key = key.split('.')[1];
181192
api += ` ${key} = ${item.value}, ` + (item.description ? `--[[ ${item.description} ]]` : '') + '\n';
182193
} else {
183-
const comment = item.description ? `${putCommentBeforeEachLine(item.description, false)}\n` : '';
184-
api += `${comment}${key} = ${item.value}\n`;
194+
api += item.description ? `${putCommentBeforeEachLine(item.description, false)}\n` : ''
195+
if (item.deprecated)
196+
api += `---@deprecated ${item.deprecated ?? ''}\n`;
197+
api += `${key} = ${item.value}\n`;
185198
}
186199
};
187200

@@ -196,14 +209,31 @@ export class GluaApiWriter {
196209
return api;
197210
}
198211

212+
private writeType(type: string, value: any) {
213+
if (type === 'string')
214+
return `'${escapeSingleQuotes(value)}'`;
215+
216+
if (type === 'Vector')
217+
return `Vector${value}`;
218+
219+
return value;
220+
}
221+
199222
private writeStruct(struct: Struct) {
200223
let fields: string = '';
201224

202225
for (const field of struct.fields) {
203-
fields += `---@field ${GluaApiWriter.safeName(field.name)} ${this.transformType(field.type)} ${removeNewlines(field.description!)}\n`;
226+
if (field.deprecated)
227+
fields += `---@deprecated ${field.deprecated ?? ''}\n`;
228+
229+
fields += `---${removeNewlines(field.description).replace(/\s+/g, ' ')}\n`;
230+
231+
const type = this.transformType(field.type)
232+
fields += `---@type ${type}\n`
233+
fields += `${struct.name}.${GluaApiWriter.safeName(field.name)} = ${field.default ? this.writeType(type, field.default) : 'nil'}\n\n`;
204234
}
205235

206-
return this.writeClass(struct.name, undefined, fields);
236+
return this.writeClass(struct.name, undefined, fields, struct.deprecated);
207237
}
208238

209239
public writePages(pages: WikiPage[]) {
@@ -254,6 +284,9 @@ export class GluaApiWriter {
254284
});
255285
}
256286

287+
if (func.deprecated)
288+
luaDocComment += `---@deprecated ${func.deprecated ?? ''}\n`;
289+
257290
return luaDocComment;
258291
}
259292

0 commit comments

Comments
 (0)