@field doesn't to work for tables

[47rooks]

How are you using the lua-language-server?

Visual Studio Code Extension (sumneko.lua)

Which OS are you using?

Windows

What is the issue affecting?

Completion, Other

Expected Behaviour

When using the table while coding I want to see the field names and their descriptions in a table which is pushed from the host program. These are various useful globals, though I'll have other examples with class instance values.

Actual Behaviour

When I mouse over or type the table name I can only see the placeholder field names and values but no description.
So I see this in the editor:

(global) FlxG: {
    height: nil,
    width: nil,
}
@table FlxG

Reproduction steps

Define a Lua file.
In my case this is really just a doc file to provide Lua completion doc in VSCode when coding to call function and use values from the host program. So I define a .lua file like:

--- Read access to global values from Flixel.
--- @field width number The width of the game window.
--- @field height number The height of the game window.
--- @table
FlxG = {
    width = nil,
    height = nil
}

This syntax comes from LDoc examples but I have tried variations - none successful. For example I have tried dropping the @table tag but that makes no difference.

Additional Notes

This is very similar to #2960 but I'm not sure whether they are identical or not. I don't get the error message seen in that issue.

Also, I note that while LDoc documents just '--' on lines after the first I find that the VSCode extension does not recognise that format. So I have to use a third '-' on all lines.

Log File

No response

[tomlau10]

This syntax comes from LDoc examples

This repo is LuaLS which uses LuaCATS annotation, and is different from LDoc.
There is no @table, meanwhile @field only works for @class.
You may want to see some examples in the official wiki: https://luals.github.io/wiki/annotations/#field

Or are you feature requesting? But I think this is by design. 😕

---

As for your case, if you only want to write a meta definition file (https://luals.github.io/wiki/definition-files/) to provide completion for that global table, you can just define the empty namespace and write those @class / @field for it:

• meta.lua

--- @meta

--- Read access to global values from Flixel.
--- @class FlxG
--- @field width number The width of the game window.
--- @field height number The height of the game window.
FlxG = {}

• test.lua

FlxG.  --< here will suggest `width` and `height`

• hover over FlxG will show the following

(global) FlxG: FlxG {
    height: number,
    width: number,
}
Read access to global values from Flixel.

[47rooks]

Thanx @tomlau10 this is very helpful. Very new to Lua so thanx for the corrections on what the LLS is using.
While direct table support might be nice this is fine for my use case.
Thanx for the links.

[tomlau10]

If you prefer direct table without using @class, then the following will work as well 👀 @47rooks

• meta.lua

---@meta

--- Read access to global values from Flixel.
FlxG = {
    width = nil,    ---@type number The width of the game window.
    height = nil,   ---@type number The height of the game window.
}

• test.lua

FlxG.  --< here will also suggest `width` and `height`

-- hover over `FlxG` will show
--[[
(global) FlxG: {
    height: number,
    width: number,
}
Read access to global values from Flixel.
]]

FlxG.height --< hover over this will show
--[[
(global) FlxG.height: number
The height of the game window.
]]

[47rooks]

Thanx again @tomlau10. Not sure. I like this a little better for not calling a table of values a class when it isn't though I may ultimately add callback functions so I'm not sure how different it will remain. But that said I get a slightly different result on mouseover:

(global) FlxG.width: number
number The width of the game window.

The width of the game window.

Note, the repeated description. I don't know why.

My meta file looks identical to yours:

--- @meta

--- Read access to global values from Flixel.
FlxG = {
    width = nil, ---@type width number The width of the game window.
    height = nil ---@type height number The height of the game window.
}

[tomlau10]

Note, the repeated description. I don't know why.

That's strange, I don't have this issue 😕

---

I like this a little better for not calling a table of values a class

In LuaLS, @class just means a type container.
And if possible I would suggest using @class because if facilitates undefined-field check.
This diagnostic would only trigger on typed variable but not for general table (for performance reason I guess).
Consider the following:

• meta.lua

---@meta

--- Read access to global values from Flixel.
FlxG = {
    width = nil,    ---@type number The width of the game window.
    height = nil,   ---@type number The height of the game window.
}

---@class FlxG2
---@field width number
---@field height number
FlxG2 = {}

• test.lua

print(FlxG.length)  --> unknown, but no warning
print(FlxG2.length) --> warning: Undefined field `length`.

• this is because FlxG2 is typed but FlxG is not.

[47rooks]

I see - that makes sense. Thx again.