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)
1
2
3
4
5
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