> ## Documentation Index
> Fetch the complete documentation index at: https://gluals.arnux.net/llms.txt
> Use this file to discover all available pages before exploring further.

# @return

> Document function return value types and descriptions.

## 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

```lua theme={null}
---@return type [name] [description]
---@return (instance) type [name] [description]
---@return (definition) type [name] [description]
```

***

## Basic usage

```lua theme={null}
---@return string name The player's name
function GetPlayerName() return "Player" end
```

***

## Multiple return values

```lua theme={null}
---@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

```lua theme={null}
---@return Player | nil player The player, or nil if not found
function FindPlayer(name) end
```

Or with `?` shorthand:

```lua theme={null}
---@return Player? player
function FindPlayer(name) end
```

***

## Default return values

You can specify a default value for a return type using the `=value` syntax:

```lua theme={null}
---@return boolean=false success Whether the operation succeeded
function SaveData() end
```

This tells GLuaLS what the value defaults to.

<Warning>
  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).
</Warning>

***

## Generic return values

```lua theme={null}
---@generic T
---@param value T
---@return T
function clone(value) return deepCopy(value) end
```

***

## Return from string-template generic capture

```lua theme={null}
---@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

```lua theme={null}
---@return fun(x: number): string formatter
function GetFormatter() end
```

***

## `(instance)` modifier

<Danger>
  This annotation is for internal use. Most projects do not need this modifier.
</Danger>

When a function returns `(instance)`, GLuaLS keeps fields and methods on that returned variable. It does not add them to the global class:

```lua theme={null}
---@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

<Danger>
  This annotation is for internal use. Most projects do not need this modifier.
</Danger>

When a function returns `(definition)`, GLuaLS registers fields on the returned variable as global class fields:

```lua theme={null}
---@return (definition) Entity
function GetEntityBase()
    return Entity
end

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