EmmyLua注解

EmmyLua注解

声明

本文中的内容属于个人总结整理而来,个人水平有限，对于部分细节难免有理解错误及遗漏之处，如果您在阅读过程中有所发现，希望您能指正，同时文章中的部分内容也参考了其它大神的文章，如果文章中的内容侵犯了您的权益，表示非常歉意，请您指出，我将尽快修改。

本文内容出处:https://emmylua.github.io/zh_CN/annotation.html

简介

本文主要是EmmyLua编辑器插件利用注解annotation功能来增加代码提示以及其它编辑器功能

需要注意的是:EmmyLua注解功能只是单纯的辅助编辑器代码提示以及其它功能，和Lua代码的实际运行逻辑没有任何关系，因为它们就是普通的Lua注释

变更说明

• 1.0.0 (2023-08-04)

  • 初次内容整理

@class类型声明注解

• 注解

  EmmyLua利用@class注解来模拟面向对象中的类，可以继承，可以定义字段/属性

  

• 完整格式

    --@class MY_TYPE[:PARENT_TYPE] [@comment]
  

• 应用目标

  • local变量
  • global变量

• 示例

    ---@class Car : Transport @define class Car extends Transport
    local cls = class()
  
    function cls:test()
    end
  

• 示例说明

  将cls变量标记为Car类，在其它地方可以使用@type注解来标记目标变量类型，以增强代码提示以及其它功能

@type类型标记注解

• 注解

  利用 @type 注解来标记目标变量的类型，以增强代码提示以及其它功能

  

• 完整格式

  ---@type MY_TYPE[|OTHER_TYPE] [@comment]
  

• 应用目标

  • local变量

    ---@type Car @instance of car
    local car1 = {}
    
    ---@type Car|Ship @transport tools, car or ship. Since lua is dynamic-typed, a variable may be of different types
    ---use | to list all possible types
    local transport = {}
    

  • global变量

    ---@type Car @global variable type
    global_car = {}
    

  • property变量

    local obj = {}
    ---@type Car @property type
    obj.car = getCar()
    

@alias别名注解

• 注解

  可以使用 @alias 将一些复杂不容易输入的类型注册为一个新的别名

• 完整格式

  ---@alias NEW_NAME TYPE
  

• 示例

  ---@alias Handler fun(type: string, data: any):void
  
  ---@param handler Handler
  function addHandler(handler)
  end
  

@param参数类型标记注解

• 注解

  利用 @param 注解来标记函数定义参数的类型，以增强代码提示以及其它功能

  

• 完整格式

  ---@param param_name MY_TYPE[|other_type] [@comment]
  

• 应用目标

  • 函数参数

    ---@param car Car
    local function setCar(car)
        ...
    end
    

    ---@param car Car
    setCallback(function(car)
        ...
    end)
    

  • for循环参数

    ---@param car Car
    for k, car in ipairs(list) do
    end
    

@return函数返回值注解

• 注解

  利用 @return 注解来标记函数的返回值类型

  

• 完整格式

  ---@return MY_TYPE[|OTHER_TYPE] [@comment]
  

• 应用目标

  • 函数

    ---@return Car|Ship
    local function create()
        ...
    end
    
    ---Here car_or_ship doesn't need @type annotation, EmmyLua has already inferred the type via "create" function
    local car_or_ship = create()
    

    ---@return Car
    function factory:create()
        ...
    end
    

@field属性注解

• 注解

  利用 @field 注解来标记某个类的额外的属性（即使这个属性没有出现在代码里）

• 完整格式

  ---@field [public|protected|private] field_name FIELD_TYPE[|OTHER_TYPE] [@comment]
  

• 应用目标

  • 在@class注解之后

    ---@class Car
    ---@field public name string @add name field to class Car, you'll see it in code completion
    local cls = class()
    

@generic泛型注解

• 注解

  利用 @generic 注解来模拟高级语言中的 泛型

  

• 完整格式

  --@generic T1 [: PARENT_TYPE] [, T2 [: PARENT_TYPE]]
  

• 应用目标

  • function

• 示例

  ---@generic T : Transport, K
  ---@param param1 T
  ---@param param2 K
  ---@return T
  local function test(param1, param2)
      -- todo
  end
  
  ---@type Car
  local car = ...
  
  local value = test(car)
  

@vararg不定参数注解

• 注解

  使用 @vararg 注解一个函数的不定参数部分的类型

• 完整格式

  ---@vararg TYPE
  

• 示例

  ---@vararg string
  ---@return string
  local function format(...)
      local tbl = { ... } -- inferred as string[]
  end
  

language内嵌语言

• 注解

  可以利用 @language 的方式来标注一段文本为某种代码格式，从而可以显示高亮

• 完整格式

  ---@language LANGUAGE_ID
  

• 示例

  ---@language JSON
  local jsonText = [[{
      "name":"Emmy"
  }]]
  

数组类型

• 注解

  可以利用 MY_TYPE[] 的方式来标注一个数据类型为数组

• 完整格式

  ---@type MY_TYPE[]
  

• 示例

  ---@type Car[]
  local list = {}
  
  local car = list[1]
  -- car. and you'll see completion
  
  for i, car in ipairs(list) do
      -- car. and you'll see completion
  end
  

字典类型

• 注解

  可以利用 table<KEY_TYPE, VALUE_TYPE> 的方式来标注一个数据类型为字典

• 完整格式

  ---@type table<KEY_TYPE, VALUE_TYPE>
  

• 示例

  ---@type table<string, Car>
  local dict = {}
  
  local car = dict['key']
  -- car. and you'll see completion
  
  for key, car in pairs(dict) do
      -- car. and you'll see completion
  end
  

函数类型

• 注解

  可以利用 fun(param:MY_TYPE):RETURN_TYPE 的方式来标注一个数据类型为函数

• 完整格式

  ---@type fun(param:MY_TYPE):RETURN_TYPE
  

• 示例

  ---@type fun(key:string):Car
  local carCreatorFn1
  
  local car = carCreatorFn1('key')
  -- car. and you see code completion
  
  ---@type fun():Car[]
  local carCreatorFn2
  
  for i, car in ipairs(carCreatorFn2()) do
      -- car. and you see completion
  end
  

字面量类型

• 注解

  字面量类型（String literal types）允许你指定字符串作为固定的代码提示，结合 @alias 特性可以起到类似“枚举”的效果

  
  
  建议使用 @alias 简化类型复杂度

  

• 示例

  ---@alias Handler fun(type: string, data: any):void
  
  ---@param event string | "'onClosed'" | "'onData'"
  ---@param handler Handler | "function(type, data) print(data) end"
  function addEventListener(event, handler)
  end
  

  ---@alias Handler fun(type: string, data: any):void
  
  ---@alias IOEventEnum string | "'onClosed'" | "'onData'"
  
  ---@param event IOEventEnum
  ---@param handler Handler | "function(type, data) print(data) end"
  function addEventListener(event, handler)
  end
  

@see引用

• 注解

  可以利用 see 的注解来标注一个引用

  

完整示例

• 示例

  ---@class Transport @parent class
  ---@public field 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