Check out the official documentation for more on Github

What are LuaLS Annotations?

LuaLS annotations are special comments prefixed with --- that provide type information to the language server. These annotations help the server understand your code better, enabling features like:

  • Type checking and error detection
  • Intelligent autocompletion
  • Better signature help

Basic Syntax and Formatting

--- This is a basic annotation
---
--- *Bold text* and /italic text/ are supported

Core Type System

LuaLS recognizes all standard Lua types, such as `nil`, `any`, `boolean`, `string`, and more.

Advanced Type Expressions

Type PatternExampleDescription
Union Typestring\vert{}numberMultiple possible types
Arraystring[]Array of specific types
Dictionary{[string]:boolean}String-keyed dictionary
Key-Valuetable<KEY,VALUE>Generic table type
Table Literal{name:string, age:number}Structured table
Functionfun(param:string): booleanFunction signature
Optionalstring?Same as string\vert{}nil

Essential Annotations with Examples

`@type` - Variable Type Declarations

---@type string
local name = "John"

---@type number[]
local scores = { 95, 87, 92 }

---@type { [string]: boolean }
local settings = { sound = true, music = false }

---@type fun(username: string): boolean
local validateUser

`@param` - Function Parameters

---@param username string The user's name
---@param age? number Optional age parameter
---@param scores number[] Array of scores
function createUser(username, age, scores)
	-- function body
end

--- Union type parameter
---@param id string | number
function findById(id) end

--- Optional parameter with ?
---@param callback? fun() Optional callback function
function processData(callback) end

`@return` - Function Return Values

--- Simple return
---@return boolean
function isValid()
	return true
end

--- Named return with description
---@return boolean success If operation succeeded
---@return string? error Error message if failed
function riskyOperation()
	return false, "Something went wrong"
end

--- Multiple returns
---@return integer count, string... names
function getNames()
	return 3, "Alice", "Bob", "Charlie"
end

`@class` - Defining Custom Types

---@class User
---@field name string
---@field email string
---@field age? number
---@field scores number[]

---@param user User
function processUser(user)
	print(user.name) -- Autocomplete works here!
end

--- Class inheritance
---@class Admin: User
---@field permissions string[]

`@alias` - Type Aliases and Enums

--- Simple type alias
---@alias UserID integer

--- Union type alias
---@alias Status "active" | "inactive" | "pending"

--- Enum with descriptions
---@alias Color
---| '"red"'    # Primary color red
---| '"green"'  # Primary color green
---| '"blue"'   # Primary color blue

---@param favoriteColor Color
function setColor(favoriteColor) end

`@enum` - Runtime Enums

---@enum LogLevel
local LOG_LEVELS = {
	DEBUG = 1,
	INFO = 2,
	WARN = 3,
	ERROR = 4,
}

---@param level LogLevel
function logMessage(level, message) end

logMessage(LOG_LEVELS.INFO, "System started") -- Type-safe!

Advanced Annotations

`@generic` - Generic Types

--- Generic function
---@generic T
---@param item T
---@return T
function identity(item)
	return item
end

--- Generic class
---@class Container<T>
---@field value T

---@type Container<string>
local stringContainer = { value = "hello" }

`@overload` - Function Overloading

---@param name string
---@param age number
---@return User
---@overload fun(name: string): User
---@overload fun(id: number): User
function createUser(name, age) end

-- All these calls are valid:
local user1 = createUser("Alice", 30)
local user2 = createUser("Bob")
local user3 = createUser(123)

`@async` - Asynchronous Functions

---@async
---@param url string
---@return string response
function fetchData(url) end

-- Language server will show "await" hint
local data = fetchData("https://api.example.com/data")

`@diagnostic` - Controlling Error Reporting

--- Disable specific diagnostics
---@diagnostic disable-next-line: unused-local
local unusedVariable = 42

--- Enable spell checking in file
---@diagnostic enable: spell-check