EmmyLua: Annotate shared tables (WoW addon namespace)

[Ketho]

Describe the bug
In World of Warcraft addons have multiple Lua files which share a table (the addon namespace). Since the language server doesn't know about that so we need to manually annotate it.

But the language server implementation does not support editing classes. You can only define it once with ---@class ns and all the other files with ---@type ns can only read from it.

To Reproduce

• file1.lua

---@class ns
local _, ns = ...
ns.test = "banana"

• file2.lua

---@type ns
local _, ns = ...
ns.hello = "world"

• file3.lua

---@type ns
local _, ns = ...

print(ns.test)
print(ns.hello)

Expected behavior
To work the same way as the IntelliJ EmmyLua plugin.

Environment:

• OS: Windows
• Client: VSCode

Referring from Ketho/vscode-wow-api#31

[flrgh]

@Ketho when I have encountered this scenario, I've found that re-declaring the class while inheriting from itself often achieves the correct behavior:

a.lua

--- My namespace
---
---@class ns
---@field test string # my test field
local ns = {
  test = "banana",
}

b.lua

---@diagnostic disable-next-line: circle-doc-class
---@class ns : ns
---@field hello string # my hello field
local ns

ns.hello = "world"

print(ns.test)
print(ns.hello)

result

So long as the language server is aware of both the original ns class and the new one, the ns class is properly extended:

I even see the proper type definition in the original file:

[Ketho]

I've found that re-declaring the class while inheriting from itself often achieves the correct behavior

That looks like a usable workaround at least, with disabling the "circularly inherited classes" warning, thanks. I do hope there will be a proper fix or maybe any better solution.

[Arxareon]

#1158 (comment)

I'm trying to do a specific thing for which definitions and annotations were recognized between different files in the past. I describe it in #Ketho/vscode-wow-api#31

TLDR: I use a global table containing subtables with tools I use between different WoW addons (they all see global variables). The tools are in subtables to account for the addons getting updates separately which may include changes to this shared toolset.
These subtables are listed with version keys (string) which are then stored within the addon namespace table local _, ns = ... (which is only used by the specific addon) so every different file the addon has can reference the same version of the toolset easily.

Overengineered? Probably. Anyhow, the problem is that I can't figure out how and where to put class definitions as workarounds in this case to be able to pull annotations through for the functions in the toolset subtable inside that global table at the specific version key which I store in the addon's namespace table.

What I have is a subclass - the subtable of the global table which has a variable name: the current version of the toolbox the specific addon uses. I don't know how to describe that in EmmyLua to be able to set recognizable field definitions for the tool functions inside. I don't know why or how exactly it worked before, but it did - or, how and when exactly it become broken.*

---

*@sumneko I was able to test past versions and everything was working in version 2.6.8 until 3.0.2 (and presumably 3.0.0 and 3.0.1 but I wasn't able to get these to versions loaded after rollback in VS Code).

Something was changed, introduced or got broken with the 3.0 update.

Temporary workaround: Roll back to version 2.6.8

[sumneko]

You can use ---@class multiple times
https://github.com/sumneko/lua-language-server/blob/c586a11e9ae9b3f001c39d7f2f6762b0cf7af671/script/vm/doc.lua#L3-L4
https://github.com/sumneko/lua-language-server/blob/c586a11e9ae9b3f001c39d7f2f6762b0cf7af671/script/vm/infer.lua#L4-L5

[Ketho]

Thank you, that works perfectly! I didn't think it could be this simple by just using @class multiple times ❤️

[Arxareon]

@sumneko Hi! After mentioning it here: #980 (comment), I still can't make it work with my use case (described in the comment linked below). I'd like to ask for some assistance to either understand what I'm supposed to add or find a fix to restore the functionality observed in the extension version 2.6.8 as seen in the demonstration in the linked comment. I was using 2.6.8 up til now but I tried updating to see if anything changed since then.
Ketho/vscode-wow-api#31 (comment)

[sumneko]

@sumneko Hi! After mentioning it here: #980 (comment), I still can't make it work with my use case (described in the comment linked below). I'd like to ask for some assistance to either understand what I'm supposed to add or find a fix to restore the functionality observed in the extension version 2.6.8 as seen in the demonstration in the linked comment. I was using 2.6.8 up til now but I tried updating to see if anything changed since then. Ketho/vscode-wow-api#31 (comment)

I think this has nothing to do with the theme of this Issue. You should open a new Issue and provide a demo code.