Annotations overview

What are annotations?

Annotations are comments that start with ---@. They give GLuaLS type information. Put them above functions, variables, and class definitions so GLuaLS can provide better completion, type checking, and hover docs.

---@param ply Player The player who joined
---@return boolean success Whether the operation succeeded
function OnPlayerJoin(ply)
    return true
end

Annotations do not affect runtime. Garry’s Mod treats them as normal comments. GLuaLS follows EmmyLua-style annotations and adds Garry’s Mod Lua extensions for realms, hooks, wrappers, and editor tooling. It keeps compatibility with EmmyLua and LuaLS where possible.

Type system annotations

Annotation	Description	Example
`@class`	Define a class with optional inheritance	`---@class Animal`
`@field`	Add a typed field to a class	`---@field health number`
`@type`	Declare the type of a variable	`---@type Player`
`@alias`	Create a new type alias	`---@alias ID string \| number`
`@enum`	Mark a table as an enumeration	`---@enum TEAM`
`@generic`	Add generic type parameters to a function	`---@generic T`
`@operator`	Document an operator overload	`---@operator add(Vector): Vector`

Function annotations

Annotation	Description	Example
`@param`	Document a parameter’s type	`---@param ply Player`
`@return`	Document a return value’s type	`---@return boolean`
`@overload`	Define an alternate function signature	`---@overload fun(x: number): number`
`@async`	Mark a function as async/coroutine-based	`---@async`
`@nodiscard`	Warn if the return value is unused	`---@nodiscard`

Garry’s Mod Lua annotations

Annotation	Description	Example
`@realm`	Declare which realm code runs in	`---@realm server`
`@hook`	Mark a function or method as a hook handler	`---@hook PlayerSpawn`
`@outparam`	Document a parameter table field modified by a function	`---@outparam cfg.output TraceResult`
`@fileparam`	Set a file-wide parameter type default	`---@fileparam ply Player`
`@accessorfunc`	Mark a function as an accessor generator	`---@accessorfunc`
`@call_arg`	Mark wrapper parameters as names, callbacks, files, or metadata	`---@[call_arg("gmod.hook", "add")]`
`Guard metadata`	Mark functions and callbacks that prove values are valid	`---@[valid_guard]`

Control and metadata annotations

Annotation	Description	Example
`@diagnostic`	Enable or disable specific diagnostics	`---@diagnostic disable-next-line`
`@cast`	Cast a variable to a different type	`---@cast ply Player`
`@deprecated`	Mark a symbol as deprecated	`---@deprecated Use NewFunc()`
`@meta`	Mark a file as type-only (not runtime)	`---@meta`
`@module`	Declare a file as a named module	`---@module mymodule`
`@see`	Add a cross-reference to another symbol	`---@see AnotherClass`
`@source`	Map a definition to its true source location	`---@source file:///path/file.lua#41:0`
`@version`	Restrict features to specific Lua versions	`---@version >5.1`

Type expression syntax

Annotations use the same type expression syntax across all @ tags:

Syntax	Meaning
`string`	A string value
`number`	A number value
`boolean`	A boolean value
`table`	Any table
`Entity`	A class by name
`string \| number`	Union type (string or number)
`string?`	Shorthand for `string \| nil`
`string[]`	An array of strings
`table<string, number>`	A table mapping strings to numbers
`fun(x: number): string`	A function type
`any`	Any value (no type checking)

Start here

Common tasks

What are annotations?

Type system annotations

Function annotations

Garry’s Mod Lua annotations

Control and metadata annotations

Type expression syntax

​What are annotations?

​Type system annotations

​Function annotations

​Garry’s Mod Lua annotations

​Control and metadata annotations

​Type expression syntax

What are annotations?

Type system annotations

Function annotations

Garry’s Mod Lua annotations

Control and metadata annotations

Type expression syntax