Description
Introduce
I'm working on the 3.X version, the purpose is to add a more complete type system, and use this to implement features such as type checking.
In previous versions I tried to keep the type system compatible with EmmyLua, but I will make some breaking changes after version 3.X, so the type system may not be suitable to continue to be called EmmyLua in the future, but I haven't thought about it yet, I will call it .LuaDoc for now
Breaking changes
Always trace local set
local x
x = 1
x = true
print(x) --> x is `integer|boolean`---@type string
local x
x = 1
x = true
print(x) --> x is `string`local x = 'str'
x = 1
x = true
print(x) --> x is `string`Dose not trace field inject
local x = {}
local y = x
y.field = 1
print(x.field) --> undefined field `field`use ---@class instead
---@class MyClass
local x = {}
---@class MyClass
local y = x
y.field = 1
print(x.field) --> `x.field` is `1`Finding definition does not recurse
local t = {}
t.x = 1
t.y = t.x
print(t.y) --> t.y is `1`Find definition of t.y will not find out t.x
---@class C
local mt = {}
---@type C
local oFind definition of o will not find out mt
Type unknown
local t = {}
print(t.x) --> t.x is `unknown` instead of `any`Types can be used in doc-table keys
---@type { [number]: string }
local t
print(t[1]) --> t[1] is `string`
print(t.x) --> t.x is `unknown`boolean type true and false
You can use ---@type { [string]: true } now.
class and alias support generic inheritance
---@class table<K, V>: { [K]: V } --> this is builtin
---@alias mark<K> { [K]: true } table<integer, string> can not convert to string[]
table<integer, string> can not convert to string[]Default value of unrary and binary
---@type unknown
local x
local y = - x --> y is `number` instead of `unknown`unknown can form union types with other types
function f()
if x then
return y
else
return nil
end
end
local n = f() --> n is `unknown|nil`Integer type
---@type 1|2|3|4|5
local vdoc-enum must be a string
---@param x 'aaa'|'bbb'
function f(x)
print(x) --> x is `"aaa"` or `"bbb"`
endThis means you can no longer use ---@param x '1024'|'true'|'function () end' to represent a specific number, boolean or function. Use ---@param x 1024|true|fun() instead.
For compatibility, I will continue to recognize '"xxx"' as the string xxx instead of "xxx".
integer is a class in Lua 5.1 and Lua 5.2
---@type integer
local v
print(v) --> v is `integer` instead of `number`Although Lua 5.1 and Lua 5.2 runtimes do not have integer, many API parameters require a number that can be converted to an integer, so adding integer to the type system can help you handle this part.
Not supported for now
search metatable in this case
setmetatable(object, { __index = {
default = 1
} })
print(object.default) --> undefined field `default`This turns the reference into a definition, and checking the reference in order to search for a definition is too expensive.
Please use ---@class or use this:
object = setmetatable(object, { __index = {
default = 1
} })
print(object.default) --> this is OKMaybe can be resolved by indexing
setmetable