Skip to main content

​
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 support for GMod-specific cases. It keeps compatibility with EmmyLua and LuaLS where possible.

​
Type system annotations

AnnotationDescriptionExample
@classDefine a class with optional inheritance---@class Animal
@fieldAdd a typed field to a class---@field health number
@typeDeclare the type of a variable---@type Player
@aliasCreate a new type alias---@alias ID string | number
@enumMark a table as an enumeration---@enum TEAM
@genericAdd generic type parameters to a function---@generic T
@operatorDocument an operator overload---@operator add(Vector): Vector

​
Function annotations

AnnotationDescriptionExample
@paramDocument a parameter’s type---@param ply Player
@returnDocument a return value’s type---@return boolean
@overloadDefine an alternate function signature---@overload fun(x: number): number
@asyncMark a function as async/coroutine-based---@async
@nodiscardWarn if the return value is unused---@nodiscard

​
GMod-specific annotations

AnnotationDescriptionExample
@realmDeclare which realm code runs in---@realm server
@hookMark a function or method as a hook handler---@hook PlayerSpawn
@outparamDocument a parameter table field modified by a function---@outparam cfg.output TraceResult
@fileparamSet a file-wide parameter type default---@fileparam ply Player
@accessorfuncMark a function as an accessor generator---@accessorfunc

​
Control and metadata annotations

AnnotationDescriptionExample
@diagnosticEnable or disable specific diagnostics---@diagnostic disable-next-line
@castCast a variable to a different type---@cast ply Player
@deprecatedMark a symbol as deprecated---@deprecated Use NewFunc()
@metaMark a file as type-only (not runtime)---@meta
@moduleDeclare a file as a named module---@module mymodule
@seeAdd a cross-reference to another symbol---@see AnotherClass
@sourceMap a definition to its true source location---@source file:///path/file.lua#41:0
@versionRestrict features to specific Lua versions---@version >5.1

​
Type expression syntax

Annotations use the same type expression syntax across all @ tags:
SyntaxMeaning
stringA string value
numberA number value
booleanA boolean value
tableAny table
EntityA class by name
string | numberUnion 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): stringA function type
anyAny value (no type checking)