changelog.md

---@enum (key) AnimalType
local enum = {
  Cat = 1,
  Dog = 2,
}

---@param animal userdata
---@param atp AnimalType
---@return boolean
local function isAnimalType(animal, atp)
  return API.isAnimalType(animal, enum[atp])
end

assert(isAnimalType(animal, 'Cat'))
---@class (exact) Point
---@field x number
---@field y number
local m = {}
m.x = 1 -- OK
m.y = 2 -- OK
m.z = 3 -- Warning
---@type number
local x

---@type number
local y

x = y

y = x --> Can not infer `y` before
---@class unit
---@field private uuid integer
---@class unit
local mt = {}

---@private
function mt:init()
end

---@protected
function mt:update()
end
---@class unit
---@field _uuid integer --> treat as private when `Lua.doc.privateName` has `"_*"`
// color global variables to red
"editor.semanticTokenColorCustomizations": {
    "rules": {
        "variable.global": "#ff0000"
    }
}
---@class myClass
local myClass = {}

myClass.a.b.c.e.f.g = 1

---@type myClass
local class

print(class.a.b.c.e.f.g) --> inferred as integer
---@class Object
local obj = setmetatable({
  initValue = 1,
}, mt)

print(obj.initValue) --> `obj.initValue` is integer
---@generic T
---@param f fun(x: T)
---@return T[]
local function x(f) end

---@type fun(x: integer)
local cb

local arr = x(cb) --> `arr` is inferred as `integer[]`
---@return fun(x: integer)
local function f()
    return function (x) --> `x` is inferred as `integer`
    end
end
---@class A
---@field f fun(x: string)

---@type A
local t = {
    f = function (x) end --> `x` is inferred as `string`
}
{
  "runtime.special": {
    "sandbox.require": "require"
  }
}
---@type fun(x: number)
local function f(x) --> `x` is inferred as `number`
end
---@generic T: string | boolean
---@param x T
---@return T
local function f(x)
    return x
end

local x = f(1) --> Warning: Cannot assign `integer` to parameter `<T:boolean|string>`.
---@type table<string, string>
local x

---@type table<string, number>
local y

x = y --> Warning: Cannot assign `<string, number>` to `<string, string>`
---@type boolean[]
local t = { 1, 2, 3 } --> Warning: Cannot assign `integer` to `boolean`
---@class fspath
---@operator div(string|fspath): fspath

---@type fspath
local root

local fileName = root / 'script' / 'main.lua' -- `fileName` is `fspath` here
-- Also supports absolute path or relative path (based on current file path)
---@source file:///xxx.c:50:20
XXX = 1 -- when finding definitions of `XXX`, returns `file:///xxx.c:50:20` instead here.
---@enum animal
Animal = {
  Cat = 1,
  Dog = 2,
}

---@param x animal
local function f(x) end

f() -- suggests `Animal.Cat`, `Animal.Dog`, `1`, `2` as the first parameter
---@type number, _, boolean
local a, b, c -- `a` is `number`, `b` is `unknown`, `c` is `boolean`
---@class BaseClass
local BaseClass

---@class MyClass: BaseClass
local MyClass = BaseClass -- OK!
--![](image.png) --> will convert to `--![](file:///xxxx/image.png)`
local x
---@class A
local a = {}

---@class B: A
local b = setmetatable({}, { __index = a }) -- OK!
local function f() end
local x = f() -- `x` is `nil` instead of `unknown`
---@overload fun(x: number, y: number):string
---@overload fun(x: number):number
---@return boolean
local function f() end

local n1 = f()     -- `n1` is `boolean`
local n2 = f(0)    -- `n2` is `number`
local n3 = f(0, 0) -- `n3` is `string`
---@type { (x: number); (y: boolean) }
---@type fun():(x: number, y: number, ...: number)
---@type `CONST.X` | `CONST.Y`
local x

if x == -- suggest `CONST.X` and `CONST.Y` here
---@type integer|nil
local n

if not n then
    error('n is nil')
end

print(n) -- `n` is `integer` here
---@type table|nil
local t

local s = t and t.x or 1 -- `t` in `t.x` is `table`
local x

if type(x) == 'string' then
    print(x) -- `x` is `string` here
end

local tp = type(x)

if tp == 'boolean' then
    print(x) -- `x` is `boolean` here
end
---@type string[]
local t

table.sort(t, function (a, b)
    -- `a` and `b` is `string` here
end)
---@class Class
---@overload fun():Class
local mt

local x = mt() --> x is `Class` here
local x = true
local y = x--[[@as integer]] -- y is `integer` here
--- @class Emit
--- @field on fun(eventName: string, cb: function)
--- @field on fun(eventName: '"died"', cb: fun(i: integer))
--- @field on fun(eventName: '"won"', cb: fun(s: string))
local emit = {}

emit:on(--[[support autocomplete fr "died" and "won"]])

emit:on("died", function (i)
    -- should be i: integer
end)

emit:on('won', function (s)
    -- should be s: string
end)
---@module 'mylib'
local lib -- the same as `local lib = require 'mylib'`
---@class keyboard
---@field ['!'] number
---@field ['?'] number
---@field ['#'] number
---@class position
---@field [1] number
---@field [2] number
---@field [3] number
local array: {
    [1]: string = "a",
    [2]: string = "b",
    [3]: string = "c",
}
---@type fun(x: "'aaa'"|"'bbb'")
local f

f(--[[show `'aaa'` and `'bbb'` here]])
---@generic T
---@param x T
---@return { x: number, y: T, z?: boolean}
local function f(x) end

local t = f('str')
-- hovering "t" shows:
local t: {
    x: number,
    y: string,
    z?: boolean,
}
---@param callback fun(value: string)
local function work(callback)
end

work(function (value)
    -- value is string here
end)
---@class Class
local mt = {}

function mt:init()
    self.xxx = 1
end

function mt:func()
    print(self.xxx) -- self.xxx is defined
end
local t = { a = 1, b = 2, c = 3 }
for k, v in pairs(t) do
    -- `k` is string and `v` is integer here
end
---before
function f(x: number)
  -> boolean
---after
local f: fun(x: number): boolean
---@class A
---@field x number
---@field y number
---@field z number

---@type A
local t = {
    -- provide `x`, `y` and `z` here
}
---this is
---a multi line
---comment
---@alias XXXX
---comment 1
---comment 1
---| '1'
---comment 2
---comment 2
---| '2'

---@param x XXXX
local function f(x)
end

f( -- view comments of `1` and `2` in completion
-- press `enter` at $
local function f() $ end
-- formating result:
local function f()
    $
end

-- as well as
do $ end
-- formating result
do
    $
end