Request: Support @field in both enum and table definitions.

[rhys-vdw]

Request: Allow adding a field type to tables and enum definitions using the @field annotation.

This is useful for generating meta files from C code where there is no Lua table literal to copy.

See current behaviour below:

@class

✅ Using @field

---@class Foo
---@field myField 5
Foo = {}

✅ Using literal code

---@class Foo
Foo = {
  myField = 5,
}

✅ Using type annotation

---@class Foo
Foo = {
  ---@type 5
  myField = nil,
}

@enum

❌ Using field

---@enum Foo
---@field myField 5
Foo = {}

Error: The field must be defined after the class.Lua Diagnostics.(doc-field-no-class)

✅ Using literal code

---@enum Foo
Foo = {
  myField = 5,
}

✅ Using type annotation

---@enum Foo
Foo = {
  ---@type 5
  myField = nil,
}

Untyped table

❌ Using field

---@field myField 5
Foo = {}

Error: The field must be defined after the class.Lua Diagnostics.(doc-field-no-class)

✅ Using literal code

Foo = {
  myField = 5,
}

✅ Using type annotation

Foo = {
  ---@type 5
  myField = nil,
}

[CppCXY]

Why do you want to write an extra annotation? Isn't it better to just use field = 5?

[rhys-vdw]

Why do you want to write an extra annotation? Isn't it better to just use field = 5?

I am just trying to make the process of exporting from C a bit easier.

An example:

https://github.com/beyond-all-reason/spring/blob/38598d14b900a9790d3e23818bf18593993249a1/rts/Lua/LuaConstCMD.cpp#L18-L82

It would be convenient to be able to just copy this out into a meta.lua file directly.

That said, I can generate Lua too, and maybe it's more appropriate.

[CppCXY]

I suggest you use AI to convert it directly:

[rhys-vdw]

I don't want to run AI in CI, I will just write a program to do it.

Thanks for the reply.

It's okay to close this issue if you don't like it. :-)

[tomlau10]

In LuaLS @enum actually works like an @alias, which it is just a type of union values: https://luals.github.io/wiki/annotations/#enum, as described in here: #2914 (comment), #2820 (comment)

---@enum T
T = {
    a = 1,
    b = 2,
}

--> the same as
---@alias T 1|2

So the type in @enum is just union of values, not a class container. When you specify an enum type in function param, the union values are checked against, instead of checking the object type. In this sense, @field seems just not fit in the concept of @enum in LuaLS. 🤔

---

With that said, there is another feature request to Add ability to define an enum without using a table: #2721, maybe it suits you better for this case and you would like to +1 to it. 😄

[rhys-vdw]

@tomlau10 thanks for the detailed response! However I don't believe either of these notations are sufficient. e.g.

---@enum MyBool
MyBool {
  ---This is true.
  myTrue = 1,

  ---This is not true.
  myFalse = 0
}

Where do I define the name and comment for myTrue and myFalse?

---@alias MyBool 1|0

But it's okay, I think it's fine to define a table. I have actually coded up a generator:
https://github.com/rhys-vdw/lua-doc-extractor

[tomlau10]

I mean the type checking behavior of @enum in LuaLS is similar to that of @alias, not requesting you to use ---@alias instead 😂 After all @enum does better job to turn a lua table in the enumeration type, and as you said allow adding comments to it.

Consider the following:

---@enum MyBool1
MyBool = {
    myFalse = 0,
    myTrue = 1,
}

---@param a MyBool1
function test1(a) end

test1(MyBool.myFalse) -- valid
test1(1) -- valid
test1(2) -- warn: param-type-mismatch

---

---@alias MyBool2 1|0
---@param a MyBool2
function test2(a) end

test2(MyBool.myFalse) -- valid
test2(1) -- valid
test2(2) -- warn: param-type-mismatch

=> they have the same type checking behavior, that's what I want to express in my previous reply 😄

---

Furthermore, @alias supports multi line mode with comments too:

---@alias MyBool3
---| 0 # myFalse, this is not true
---| 1 # myTrue, this is true
---@param a MyBool3
function test3(a) end

Then when you hover over the function test3(), the hover preview will be:

function test3(a: MyBool3)
a:
    | 0 -- myFalse, this is not true
    | 1 -- myTrue, this is true

[rhys-vdw]

Wow, that's great @tomlau10. Okay, I think the level of support is reasonable and it's up to me to decide on how I want to handle the annotations on the C side then.

Thank you so much for the detailed and quick response! 🙏