Breaking changes in 3.X

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 o

Find 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[]

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 v

doc-enum must be a string

---@param x 'aaa'|'bbb'
function f(x)
    print(x) --> x is `"aaa"` or `"bbb"`
end

This 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 OK

Maybe can be resolved by indexing setmetable

Comece lendo as breaking changes de 3.X listadas na issue e o caso de metatable não suportado; nenhum arquivo de implementação, teste ou ponto de entrada é mencionado. Antes de codificar, esclareça quais mudanças no sistema de tipos estão dentro do escopo e defina testes para os exemplos documentados e o comportamento de compatibilidade.