Skip to main content

​
Overview

@return declares the type or types a function returns. Lua functions can return multiple values, so add one @return line for each return value.

​
Syntax

---@return type [name] [description]
---@return (instance) type [name] [description]
---@return (definition) type [name] [description]

​
Basic usage

---@return string name The player's name
function GetPlayerName() return "Player" end

​
Multiple return values

---@return boolean success Whether the operation succeeded
---@return string message Status message
function DoOperation()
    return true, "OK"
end

local ok, msg = DoOperation()
-- ok: boolean, msg: string ✅

​
Optional return values

---@return Player | nil player The player, or nil if not found
function FindPlayer(name) end
Or with ? shorthand: 
---@return Player? player
function FindPlayer(name) end

​
Default return values

You can specify a default value for a return type using the =value syntax: 
---@return boolean=false success Whether the operation succeeded
function SaveData() end
This tells GLuaLS what the value defaults to.
The default value must come directly after the type, before the name:
  • ---@return boolean=false success — ✅ Correct.
  • ---@return boolean success=false — ❌ Incorrect. (This makes =false part of the description instead).

​
Generic return values

---@generic T
---@param value T
---@return T
function clone(value) return deepCopy(value) end

​
Return from string-template generic capture

---@generic T : Entity
---@param class `T`
---@return T
function ents.Create(class) end

---@generic T : Entity
---@param class `T`
---@return T[]
function ents.FindByClass(class) end
Use `T` for string-literal class names. Plain T captures value type (string), not class type. Quick rule:
  • T returns value-based types ("x" -> string)
  • `T` returns class/type names from string literals ("sent_npc" -> sent_npc)

​
Function return values

---@return fun(x: number): string formatter
function GetFormatter() end

​
(instance) modifier

This annotation is for internal use. Most projects do not need this modifier.
When a function returns (instance), GLuaLS keeps fields and methods on that returned variable. It does not add them to the global class: 
---@return (instance) Panel
function CreateMyPanel()
    return vgui.Create("DPanel")
end

local panel = CreateMyPanel()
function panel:Refresh() end  -- Only on this panel instance

local other = CreateMyPanel()
other:Refresh()  -- ❌ Error: Refresh doesn't exist here
Use this for factory functions that return panels or entities with custom methods.

​
(definition) modifier

This annotation is for internal use. Most projects do not need this modifier.
When a function returns (definition), GLuaLS registers fields on the returned variable as global class fields: 
---@return (definition) Entity
function GetEntityBase()
    return Entity
end

local base = GetEntityBase()
base.MyNewMethod = function(self) end -- Added to all Entity instances globally