Skip to content

EmmyLua Annotations

Jump to bottom
最萌小汐 edited this page Nov 17, 2021 · 76 revisions

Disclaimer: This article was written by a user in an effort to get basic documentation.

EmmyLua annotations are doc comments similar to LDoc tags, but besides adding documentation they are used to improve features like code completion and signature information. Also refer to the official documentation and Luanalysis (EmmyLua fork), although Sumneko's implementation might not be the same.

Table of Contents

Annotations

@param

Specifies the type of function params.

---@param r number
---@param g number
---@param b number
function SetColor(r, g, b) end

@return

Specifies the type of function returns. Note that the return name is optional.

---@return string firstName
---@return string middleName
---@return string lastName
function GetName() end
---@return string, string, string 
function GetName() end
---@return string firstName, string middleName, string lastName
function GetName() end

@class

Defines classes.

---@class Animal
---@field legs number
local Animal = {}
function Animal:Walk() end

---@class Pet
---@field ownerName string

---@class Cat : Animal, Pet

---@type Cat
local gamercat = {}

@field

Declares a field on a class. For example a table/structure can be annotated as a class with fields.

---@param id number
---@return BNetAccountInfo accountInfo
function GetAccountInfoByID(id) end

---@class BNetAccountInfo
---@field accountName string
---@field isFriend boolean
---@field gameAccountInfo BNetGameAccountInfo

---@class BNetGameAccountInfo
---@field gameAccountID number
---@field characterName string

local info = GetAccountInfoByID(1)
print(info.gameAccountInfo.characterName)

Types and @type

Known types are: nil, any, boolean, string, number, integer, function, table, thread, userdata, lightuserdata

  • Classes can be used and passed or returned as a type.
  • Multiple types are separated with | 
---@param nameOrIndex string|number
---@return table|nil info
function GetQuestInfo(nameOrIndex) end

  • @type specifies the type of a variable.
  • Arrays are indicated with a [] 
---@type string[]
local msg = {"hello", "world"}
  • Tables are formatted as table<KEY_TYPE, VALUE_TYPE> 
---@type table<string, number>
local CalendarStatus = {
	Invited = 0,
	Available = 1,
	Declined = 2,
	Confirmed = 3,
}
  • Functions are formatted as fun(param: VALUE_TYPE): RETURN_TYPE and are used in e.g. @overload 
fun(x: number): number

Comments

There are multiple ways to format comments. The @ and # symbols can be used to (explicitly) begin an annotation comment. This is useful for @return if you don't want to specify a param name but do want to add a comment.

---@param apple string hello 1
---@return string banana hello 2
---@return string @hello 3
---@return string #hello 4
function Foo(apple) end

Comments support Markdown formatting. To create a line break, use two trailing spaces (#526), note it will trigger the trailing-space diagnostic hint.

--this is a **valid** comment  
---this is *also* valid and on a newline
---
--- this is a new paragraph
--- [Click me](https://www.google.com/)
--- ```
--- for i, v in ipairs(tbl) do
--- 	-- do stuff
--- end
--- ```
--- - item 1
---   - level 2
---@param tbl table comment for `tbl`
function Foo(tbl) end

Optional Params

Appending a question mark (after the first word) marks a param optional/nilable. Another option is to instead use |nil as a second type.

---@param prog  string
---@param mode? string
---@return file*?
---@return string? errmsg
function io.popen2(prog, mode) end

@vararg

Indicates a function has multiple variable arguments.

---@vararg string
---@return string
function strconcat(...) end

For returning a vararg you can use ... as a type.

---@vararg string
---@return ...
function tostringall(...) end

@alias

Aliases are useful for reusing param types e.g. a function or string literals.

---@alias exitcode2 '"exit"' | '"signal"'

---@return exitcode2
function io.close2() end

---@return exitcode2
function file:close2() end

String literals for an alias can be listed on multiple lines and commented with #

---@alias popenmode3
---| '"r"' # Read data from this program by `file`.
---| '"w"' # Write data to this program by `file`.

---@param prog string
---@param mode popenmode3
function io.popen3(prog, mode) end

@overload

Specifies multiple signatures.

---@param tbl table
---@param name string
---@param hook function
---@overload fun(name: string, hook: function)
function hooksecurefunc(tbl, name, hook) end

@generic

Simulates generics.

---@class Foo
local Foo = {}
function Foo:Bar() end

---@generic T
---@param name `T`
---@return T
function Generic(name) end

local v = Generic("Foo") -- v is an object of Foo

@diagnostic

Controls diagnostics for errors, warnings, information and hints (script/proto/define.lua)

  • disable-next-line - Disables diagnostics for the next line.
  • disable-line
  • disable - Disables diagnostics for the file.
  • enable - Enables diagnostics for the file.
---@diagnostic disable-next-line: unused-local
function hello(test) end

The diagnostics state behaves as a toggle.

@module

Provide the semantics of require

---@module'mylib.module'
local module -- same as `local module = require 'mylib.module'`

@version

Marks if a function or class is exclusive to specific Lua versions: 5.1, 5.2, 5.3, 5.4, JIT. Requires configuring Diagnostics: Needed File Status (#494).

---@version >5.2,JIT
function hello() end
---@version 5.4
function Hello() end

print(Hello())

@deprecated

Visibly marks a function as deprecated.

@see

Functionally the same as an annotation comment.

@meta

This is for internal use by Sumneko. The mark will have some details on the impact, and may continue to increase in the future. Currently they are:

  • completion will not display context in a meta file
  • hover of require a meta file shows [[meta]] instead of absolute path
  • find reference ignores results in a meta file

Settings

There are a few notable EmmyLua options one should consider changing.

Completion: Display Context

"Lua.completion.displayContext": 6 (default)

"Lua.completion.displayContext": 0

References

Clone this wiki locally