Annotate global declarations

[Real-Gecko]

I have a project with some @meta files added to workspace.library. This files are created by myself to describe functions and global variables that're inherited from elsewhere when code is executed. While defining classes and functions works fine, declaring globals with types is kinda inconvenient.

---@type integer
player_min = nil

Maybe something like this would be possible?

---@global integer
player_min

Or maybe even a separate file with some tag would be possible?

---@meta globals
---@integer player_min
---@integer player_max
...

[Real-Gecko]

Or maybe something like this would work:

table.insert(_G, {
    player_min ---@integer
    player_max ---@integer
}

[tomlau10]

I just found that there is already a built-in _G class defined in the extension's basic.lua, representing the global variable .
(You can look it up by ctrl+click a _G to goto its definition)
So you can just extend this _G class in your meta file by writing:

---@class _G
---@field player_min integer
---@field player_max integer

This way will add player_min and player_max with you specified type to LuaLs's _G.

[tomlau10]

😕 With this annotation syntax, however, I found that no autocompletion is provided.
Maybe just writing each of them in one line is better:

player_min = nil ---@type integer
player_max = nil ---@type integer

[Real-Gecko]

Would be nice to declare globals without assigning values to 'em, because something like
player_min = 1 is misleading, you get a lot of hints about value being 1 which might not be true as globals are defined by runtime(executed outside of Lua code).
And something like player_min = nil usually leads to linting errors, like trying to pass nil argument to function that requires integer argument

[tomlau10]

And something like player_min = nil usually leads to linting errors, like trying to pass nil argument to function that requires integer argument

If you are writing a meta definition file, you will add the ---@meta in it, then LuaLs will ignore these kinds of warnings in this file, like duplicated fields / type mismatch something like that.

In terms of syntax, I think the ---@class _G + ---@field seems the best, as it is consistent with other class field annotation. I expected the defined fields will get merged to global namespace for autocompletion but unfortunately no. ☹️
Maybe should open an issue instead.

[tomlau10]

I definitely think that this is a bug, because with my proposed syntax above, I can get autocompletion by writing _G._G.p<here> 😂

---@class _G
---@field player_min integer
---@field player_max integer

print(p--[[no completion]])
print(_G.p--[[still no completion]])
print(_G._G.p--[[!!! has completion here !!!]])

I am going to open an issue 😄

---

edit:
I just found that there is already a better global under planning. 🤔

edit2:
I just opened an issue to track this: #2714

[Real-Gecko]

Cool, let's wait for it to be fixed.