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

# Annotations overview

> EmmyLua/LuaCATS type annotations supported by GLuaLS.

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

```lua theme={null}
---@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`](/annotations/class)       | Define a class with optional inheritance  | `---@class Animal`                 |
| [`@field`](/annotations/field)       | Add a typed field to a class              | `---@field health number`          |
| [`@type`](/annotations/type)         | Declare the type of a variable            | `---@type Player`                  |
| [`@alias`](/annotations/alias)       | Create a new type alias                   | `---@alias ID string \| number`    |
| [`@enum`](/annotations/enum)         | Mark a table as an enumeration            | `---@enum TEAM`                    |
| [`@generic`](/annotations/generic)   | Add generic type parameters to a function | `---@generic T`                    |
| [`@operator`](/annotations/operator) | Document an operator overload             | `---@operator add(Vector): Vector` |

## Function annotations

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

## Garry's Mod Lua annotations

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

## Control and metadata annotations

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