Lua EmmyLua 注解詳解

Why

• 為了使 IDE 編碼體驗和強語言相近
• 讓 IDE 提前發現編碼錯誤
• BUG 查找更方便
• 代碼閱讀更方便

建議

• 明確字段類型
• 明確字段訪問修飾符
• 明確方法參數類型
• 善用 ":" 繼承 "|" 或 ","多個

支持格式

--類            ---@class MY_TYPE[:PARENT_TYPE] [@comment]
--類型          ---@type MY_TYPE[|OTHER_TYPE] [@comment]
--別名          ---@alias NEW_NAME TYPE
--參數          ---@param param_name MY_TYPE[|other_type] [@comment]
--返回值        ---@return MY_TYPE[|OTHER_TYPE] [@comment]
--字段          ---@field [public|protected|private] field_name FIELD_TYPE[|OTHER_TYPE] [@comment]
--泛型          ---@generic T1 [: PARENT_TYPE] [, T2 [: PARENT_TYPE]]
--不定參數      ---@vararg TYPE
--內嵌語言      ---@language LANGUAGE_ID
--數組          ---@type MY_TYPE[]
--字典          ---@type table<KEY_TYPE, VALUE_TYPE>
--函數          ---@type fun(param:MY_TYPE):RETURN_TYPE

官網完整例子

---@class Transport @parent class
---@field public name string
local transport = {}

function transport:move() end

---@class Car : Transport @Car extends Transport
local car = {}
function car:move() end

---@class Ship : Transport @Ship extends Transport
local ship = {}

---@param type number @parameter type
---@return Car|Ship @may return Car or Ship
local function create(type)
    -- ignored
end

local obj = create(1)
---now you can see completion for obj

---@type Car
local obj2
---now you can see completion for obj2

local list = { obj, obj2 }
---@param v Transport
for _, v in ipairs(list) do
    ---not you can see completion for v
end

自己驗證例子

---@class TestBase @基類
---@field protected key number @基類字段

---@class Test : TestBase @測試類
---@field bool boolean @boolean 類型字段
---@field numberArray number[] @數組
---@field numberDictionary table<number,number> @字典

---@type Test
local Test = {}

---@type number @number 類型字段（后期擴展字段 IDE 不能識別注釋）
Test.num = 0

---方法 1
function Test:Func1()
    --字段測試
    self.key = 0 --能跳轉基類
    self.bool = false
    self.num = 1 --IDE 不能識別注釋
    for i, v in ipairs(self.numberArray) do end
    for k, v in pairs(self.numberDictionary) do end --遍歷能識別 k v 類型

    --方法測試
    self:Func2("張三")
    local tempFunc3 = self:Func3("李四")
    local tempFunc4A, tempFunc4B = self:Func4("王五", false)
    local tempFunc5 = self:Func5(false)
end

---方法 2 有參數
---@param name string @名字
function Test:Func2(name)
end

---方法 3 有返回值
---@return string @返回類型
function Test:Func3(name)
    return name
end

---方法 4 多參數 多返回值
---@param name string @名字
---@param sex boolean @性別
---@return string , number @返回類型
function Test:Func4(name, sex)
    return name, sex
end

---方法 5 參數多類型 返回值多類型
---@param sex string | boolean @性別
---@return string | boolean @返回類型
function Test:Func5(sex)
    return sex
end

---方法 6 參數為方法
---@param func fun(key:number):string @函數
function Test:Func6(func)
    return func(1)
end

--使用 see 注解來標注一個引用
---@see Test#Func1

--下面的不常用

--不定參數注解
---@vararg string
---@return string
local function format(...)
    local tbl = { ... } -- inferred as string[]
end

--泛型
--幾乎不用 C#用是因為用 object 作為參數 有裝箱拆箱消耗 lua 語言天然不需要

---@class Goods @物品基類
---@field public price number @價格

---@class Food : Goods @食物
---@field public cal number @卡路里

---@class Phone : Goods @手機
---@field public battery number @電量

---@generic T : Goods
---@param object T
function Test:GetPrice(object)
    return object.price
end

--內嵌語言
---@language JSON
local jsonText = [[{
    "name":"Emmy"
}]]

return Test