Annotating members of a table in a global table which are initialized within a function, VSCode integration

[sparr]

I am working on adding annotations to https://github.com/beyond-all-reason/Beyond-All-Reason/tree/master/luaui/Widgets. A convention among these files is that they expect a global table named WG to exist. A single widget file will typically create one entry in the WG table. That entry is itself a table with most of its values being functions. For example, WG.FlowUI.guishaderCheckDlist() or WG['info'].clearDisplayUnitID() or WG.TerraformBrush.setAngleSnapStep(). These functions form the exposed API for the widget in question, which other widgets might call by referencing that WG table.

Some widgets create their WG entry at the top level of the widget script, to be run when the script is first loaded.
Some widgets create their WG entry in an Initialize function that will get called by the widget loader.
Some WG entries are created one entry at a time, e.g. WG.info = {} WG.info['foo'] = bar.
Some WG entries are created with an inline table, e.g. WG.info = {foo = bar}.

I would like to be able to annotate every WG.foo.bar at the point where it is defined, such that the language server will correctly associate that with references to WG.foo.bar in other files. I'm having a difficult time getting this to work, particularly using the Lua extension in VSCode, although I'm open to trying to interact directly with LuaLS for troubleshooting purposes.

One approach I've tried is to use class/field annotations at each function definition site:

	---@class WG.buildmenu
	---@field getGroups fun(): table<string, string>, table<UnitDefID, number> groupIconPaths, unitDefIDToGroup
	WG['buildmenu'].getGroups = function()
		return groups, units.unitGroup
	end

This makes "Go To Definition" work seamlessly in VSCode, but the tooltip for WG.buildmenu.getGroups in other files now suggests that getGroups is a union type of the function or the whole class.

Another approach is to use type annotations:

	---@type fun(): table<string, string>, table<UnitDefID, number> groupIconPaths, unitDefIDToGroup
	WG['buildmenu'].getGroups = function()
		return groups, units.unitGroup
	end

This produces the expected/desired tooltip which shows the signature of the function, but now "Go To Definition" gets confused and forces me to choose between the annotation or the definition.

Is there one best way to do this without any of these drawbacks, across all the various ways the tables are populated?

[tomlau10]

but the tooltip for WG.buildmenu.getGroups in other files now suggests that getGroups is a union type of the function or the whole class.

The @class annotation will be binded to the next immediate variable declared after it. (unless you separate an empty line)
In you case because WG['buildmenu'].getGroups is the immediate variable after @class WG.buildmenu
=> therefore WG['buildmenu'].getGroups will be given the whole class type WG.buildmenu

---

I believe what you want to do is just like the following: 🤔

---@class UnitDefID
---@class unitDefIDToGroup

---@class WG # actually this may not be needed
WG = {}

local groups = {}
local units = {}

---@class WG.buildmenu
WG['buildmenu'] = {}

---@return table<string, string>
---@return table<UnitDefID, number> groupIconPaths
---@return unitDefIDToGroup
WG['buildmenu'].getGroups = function()
    return groups, units.unitGroup
end

• bind @class WG.buildmenu to only the WG['buildmenu'] = {} object
• after you declare the WG['buildmenu'] = {} table as WG.buildmenu class
  every function field injection to this table will be auto injected into the class WG.buildmenu
• then annotate WG['buildmenu'].getGroups just like a standard function

---

⚠️ However I am not sure why, the Go To Definition still gives 2 results 🤷‍♂️ though they both point to the same line

• one is the getGroups variable
• another one is the function () body

Maybe this is due to function declare style module.func = function () ...
If you declare it as function WG.buildmenu.getGroups() then goto definition will auto follow it 🤔