⚠️ Warning

This wiki has been replaced by the wiki on our website. This wiki will be removed in the future.

The language server does its best to infer types through contextual analysis, however, sometimes manual documentation is necessary to improve completion and signature information.

Annotations are prefixed with ---, like a Lua comment with one extra dash. To learn more, check out Formatting Annotations.

Note The annotations used by the server are based off of EmmyLua annotations but a rename is in progress.

⚠️ Warning: The annotations used by the server are no longer cross-compatible with EmmyLua annotations since v3.0.0.

The annotations are also described in script.lua which can be found in multiple languages in locale/. Corrections and translations can be provided in these script.lua files and submitted through a pull request.

• If you type --- one line above a function, you will receive a suggested snippet that includes @param and @return annotations for each parameter and return value found in the function.

Properly documenting types with the language server is very important and where a lot of the features and advantages are. Below is a list of all recognized Lua types (regardless of version in use):

• nil
• any
• boolean
• string
• number
• integer
• function
• table
• thread
• userdata
• lightuserdata

You can also simulate classes and fields and even create your own types.

Adding a question mark ? after a type like boolean? or number? is the same as saying boolean|nil or number|nil. This can be used to specify that something is either a specified type or nil. This can be very useful for function returns where a value or nil can be returned.

Below is a list of how you can document more advanced types:

Unions may need to be placed in parentheses in certain situations, such as when defining an array that contains multiple value types:

---@type (string | integer)[]
local myArray = {}

To get an understanding of how to use the annotations described on this page, you'll need to know how to read the Syntax sections of each annotation.

Any other symbols are syntactically required and should be copied verbatim.

If this is confusing, take a look at a couple examples under an annotation and it should make more sense.

Below is a list of all annotations recognized by the language server:

An alias can be useful when re-using a type. It can also be used to provide an enum. If you are looking for an enum and already have the values defined in a Lua table, take a look at @enum.

Syntax

---@alias <name> <type>

or

---@alias <name>
---| '<value>' [# description]

Note The above pipe character (|) on the left is necessary for each line and does not signify an "or".

Examples

---@alias userID integer The ID of a user

---@alias modes "r" | "w"

---@alias side
---| '"left"' # The left side of the device
---| '"right"' # The right side of the device
---| '"top"' # The top side of the device
---| '"bottom"' # The bottom side of the device
---| '"front"' # The front side of the device
---| '"back"' # The back side of the device

---@param side side
local function checkSide(side) end

local A = "Hello"
local B = "World"

---@alias myLiteralAlias `A` | `B`

---@param x myLiteralAlias
function foo(x) end

local A = "Hello"
local B = "World"

---@alias myLiteralAliases
---|`A` # Will offer completion for A, which has a value of "Hello"
---|`B` # Will offer completion for B, which has a value of "World"

---@param x myLiteralAliases
function foo(x) end

Force a type onto an expression.

⚠️ Warning: This annotation cannot be added using ---@as <type> - it must be done like --[[@as <type>]].

Note When marking an expression as an array, such as string[], you must use --[=[@as string[]]=] due to the extra square brackets causing parsing issues.

Syntax

--[[@as <type>]]

Note The square brackets in the above syntax definition do not refer to it being optional. Those square brackets must be used verbatim.

Examples

---@param key string Must be a string
local function doSomething(key) end

local x = nil

doSomething(x --[[@as string]])

Mark a function as being asynchronous. When hint.await is true, functions marked with @async will have an await hint displayed next to them. Used by diagnostics from the await group.

Syntax

---@async

Examples

---@async
---Perform an asynchronous HTTP GET request
function http.get(url) end

Cast a variable to a different type or types

Syntax

---@cast <value_name> [+|-]<type|?>[, [+|-]<type|?>...]

Examples

---@type integer
local x

---@cast x string
print(x) --> x: string

---@type integer
local x

---@cast x +boolean
print(x) --> x: integer | boolean

---@type integer|string
local x

---@cast x -integer
print(x) --> x: string

---@type string
local x --> x: string

---@cast x +boolean, +number
print(x) --> x:string | boolean | number

---@type string
local x

---@cast x +?
print(x) --> x:string?

Define a class. Can be used with @field to define a table structure. Once a class is defined, it can be used as a type for parameters, returns, and more. A class can also inherit from a parent class.

Syntax

---@class <name>[: <parent>]

Examples

---@class Car
local Car = {}

---@class Vehicle
local Vehicle = {}

---@class Plane: Vehicle
local Plane = {}

Mark a function as deprecated. This will trigger the deprecated diagnostic, displaying it as struck through.

Syntax

---@deprecated

Examples

---@deprecated
function outdated() end

Toggle diagnostics for the next line, current line, or whole file.

Syntax ---@diagnostic <state>:<diagnostic>

state options:

• disable-next-line (Disable diagnostic on the following line)
• disable-line (Disable diagnostic on this line)
• disable (Disable diagnostic in this file)
• enable (Enable diagnostic in this file)

Examples

---@diagnostic disable-next-line: unused-local

---@diagnostic enable:spell-check

Mark a Lua table as an enum, giving it similar functionality to @alias, only the table is still usable at runtime.

View Original Request

Syntax

---@enum <name>

Examples

---@enum colors
local COLORS = {
	black = 0,
	red = 2,
	green = 4,
	yellow = 8,
	blue = 16,
	white = 32
}

---@param color colors
local function setColor(color) end

setColor(COLORS.green)

Define a field within a table. Should be immediately following a @class. As of v3.6.0, you can mark a field as private, protected, public, or package.

Syntax

Note \[ and \] below mean literal [ and ]

---@field [scope] <name> <type> [description]
---@field [scope] \[<type>\] <type> [description]

Examples

---@class Person
---@field height number The height of this person in cm
---@field weight number The weight of this person in kg
---@field firstName string The first name of this person
---@field lastName string The last name of this person
---@field age integer The age of this person

---@param person Person
local function hire(person) end

---@class Animal
---@field private legs integer
---@field eyes integer

---@class Dog:Animal
local myDog = {}

---Child class Dog CANNOT use private field legs
function myDog:legCount()
	return self.legs
end

---@class Animal
---@field protected legs integer
---@field eyes integer

---@class Dog:Animal
local myDog = {}

---Child class Dog can use protected field legs
function myDog:legCount()
	return self.legs
end

---@class Numbers
---@field named string
---@field [string] integer
local Numbers = {}

Generics allow code to be reused and serve as a sort of "placeholder" for a type. Surrounding the generic in backticks (`) will capture the value and use it for the type. Generics are still WIP.

Syntax

---@generic <name> [:parent_type] [, <name> [:parent_type]]

Examples

---@generic T : integer
---@param p1 T
---@return T, T[]
function Generic(p1) end

-- v1: string
-- v2: string[]
local v1, v2 = Generic("String")

-- v3: integer
-- v4: integer[]
local v3, v4 = Generic(10)

---@class Vehicle
local Vehicle = {}
function Vehicle:drive() end

---@generic T
---@param class `T` # the type is captured using `T`
---@return T       # generic type is returned
local function new(class) end

-- obj: Vehicle
local obj = new("Vehicle")

---@class table<K, V>: { [K]: V }

---@class Array<T>: { [integer]: T }

---@type Array<string>
local arr = {}

-- Warns that I am assigning a boolean to a string
arr[1] = false

arr[3] = "Correct"

---@class Dictionary<T>: { [string]: T }

---@type Dictionary<boolean>
local dict = {}

-- no warning despite assigning a string
dict["foo"] = "bar?"

dict["correct"] = true

Marks a file as "meta", meaning it is used for definitions and not for its functional Lua code. Used internally by the language server for defining the built-in Lua libraries. If you are writing your own definition files, you will probably want to include this annotation in them. If you specify a name, it will only be able to be required by the given name. Giving the name _ will make it unable to be required. Files with the @meta tag in them behave a little different:

• Completion will not display context in a meta file
• Hovering a require of a meta file will show [meta] instead of its absolute path
• Find Reference ignores meta files

Syntax

---@meta [name]

Examples

---@meta

Simulates require-ing a file.

Syntax

---@module '<module_name>'

Examples

---@module 'http'

--The above provides the same as
require 'http'
--within the language server

---@module 'http'
local http

--The above provides the same as
local http = require 'http'
--within the language server

Mark a function as having return values that cannot be ignored/discarded. This can help users understand how to use the function as if they do not capture the returns, a warning will be raised.

Syntax

---@nodiscard

Examples

---@return string username
---@nodiscard
function getUsername() end

Provides type declarations for an operator metamethod.

View Original Request

Syntax

---@operator <operation>[(input_type)]:<resulting_type>

ℹ️ Note: This syntax differs slightly from the fun() syntax used for defining functions. Notice that the parentheses are optional here, so @operator call:integer is valid.

Examples

---@class Vector
---@operator add(Vector): Vector

---@type Vector
local v1
---@type Vector
local v2

--> v3: Vector
local v3 = v1 + v2

---@class Passcode
---@operation unm:integer

---@type Passcode
local pA

local pB = -pA
--> integer

---@class URL
---@operator call:string
local URL = {}

Define an additional signature for a function. This does not allow descriptions to be provided for the new signature being defined - if you want descriptions, you are better off writing out an entire function with the same name but different @param and @return annotations.

Syntax

---@overload fun([param: type[, param: type...]]): [return_value[, return_value]]

Examples

---@param objectID integer The id of the object to remove
---@param whenOutOfView boolean Only remove the object when it is not visible
---@return boolean success If the object was successfully removed
---@overload fun(objectID: integer): boolean
local function removeObject(objectID, whenOutOfView) end

---@overload fun(a: string): boolean
local foo = setmetatable({}, {
	__call = function(a)
		print(a)
        return true
	end,
})

local bool = foo("myString")

Mark a function as private to the file it is defined in. A packaged function cannot be accessed from another file.

Syntax

---@package

Examples

---@class Animal
---@field private eyes integer
local Animal = {}

---@package
---This cannot be accessed in another file
function Animal:eyesCount()
    return self.eyes
end

Define a parameter for a function. This tells the language server what types are expected and can help enforce types and provide completion. Putting a question mark (?) after the parameter name will mark it as optional, meaning nil is an accepted type. The type provided can be an @alias, @enum, or @class as well.

Syntax

---@param <name[?]> <type[|type...]> [description]

Examples

---@param username string The name to set for this user
function setUsername(username) end

---@param setting string The name of the setting
---@param value string|number|boolean The value of the setting
local function settings.set(setting, value) end

---@param role string The name of the role
---@param isActive? boolean If the role is currently active
---@return Role
function Role.new(role, isActive) end

---@param index integer
---@param ... string Tags to add to this entry
local function addTags(index, ...) end

---@class Box

---@generic T
---@param objectID integer The ID of the object to set the type of
---@param type `T` The type of object to set
---@return `T` object The object as a Lua object
local function setObjectType(objectID, type) end

--> boxObject: Box
local boxObject = setObjectType(1, "Box")

---@param mode string
---|"'immediate'"  # comment 1
---|"'async'" # comment 2
function bar(mode) end

local A = 0
local B = 1

---@param active integer
---| `A` # Has a value of 0
---| `B` # Has a value of 1
function set(active) end

Mark a function as private to a @class. Private functions can be accessed only from within their class and are not accessable from child classes.

Syntax

---@private

Examples

---@class Animal
---@field private eyes integer
local Animal = {}

---@private
function Animal:eyesCount()
    return self.eyes
end

---@class Dog:Animal
local myDog = {}

---NOT PERMITTED!
myDog:eyesCount();

Mark a function as protected within a @class. Protected functions can be accessed only from within their class or from child classes.

Syntax

---@protected

Examples

---@class Animal
---@field private eyes integer
local Animal = {}

---@protected
function Animal:eyesCount()
    return self.eyes
end

---@class Dog:Animal
local myDog = {}

---Permitted because function is protected, not private.
myDog:eyesCount();

Define a return value for a function. This tells the language server what types are expected and can help enforce types and provide completion.

Syntax

---@return <type> [<name> [comment] | [name] #<comment>]

Examples

---@return boolean
local function isEnabled() end

---@return boolean enabled
local function isEnabled() end

---@return boolean enabled If the item is enabled
local function isEnabled() end

---@return boolean # If the item is enabled
local function isEnabled() end

---@return boolean|nil error
local function makeRequest() end

---@return integer count Number of nicknames found
---@return string ...
local function getNicknames() end

Currently has no function other than allowing you to add a basic comment. This is not shown when hovering and has no additional functionality yet.

Syntax

---@see

Examples

---@see http.get
function request(url) end

Provide a reference to some source code which lives in another file. When searching for the defintion of an item, its @source will be used.

Syntax

@source <path>

Examples

---@source C:/Users/me/Documents/program/myFile.c
local a

---@source file:///C:/Users/me/Documents/program/myFile.c:10
local b

---@source local/file.c
local c

---@source local/file.c:10:8
local d

Mark a variable as being of a certain type. Union types are separated with a pipe character |. The type provided can be an @alias, @enum, or @class as well. Please note that you cannot add a field to a class using @type, you must instead use @class.

Syntax

---@type <type>

Examples

---@type boolean
local x

---@type boolean|number
local x

---@type string[]
local names

---@type { [string]: boolean }
local statuses

---@type table<userID, Player>
local players

---@type boolean|number|"yes"|"no"
local x

---@type fun(name: string, value: any): boolean
local x

🚮 DEPRECATED 🚮

This annotation has been deprecated and is purely for legacy support for EmmyLua annotations.

You should instead use @param for documenting parameters, variable or not.

Mark a function as having variable arguments. For variable returns, see @return.

Syntax

---@vararg <type>

Examples

---@vararg string
function concat(...) end

Mark the required Lua version for a function or @class.

Syntax

---@version [<|>]<version> [, [<|>]version...]

Possible version values:

• 5.1
• 5.2
• 5.3
• 5.4
• JIT

Examples

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

---@version 5.4
---@class Entry

Found an issue? Report it on the issue tracker.

Unit tests for the annotations can be found in test/definition/luadoc.lua.