Typing your own code

The API dataset covers everything Garry’s Mod ships. Your own functions are the gap: function MyAddon.CanPlace(ply) gives the editor nothing to work with. There are two ways to close it, and you can mix them freely.

Annotations

The same ---@param dialect the Lua Language Server uses, so annotations you already have work here, and anything you write keeps working there.

--- Returns true when the player may place a turret.
---@param ply Player
---@param count? number how many they already have
---@return boolean
function MyAddon.CanPlace(ply, count)
  return ply:IsAdmin()
end

Prose stays prose. --- Returns true when… shows up in hover; the @param lines do not.

Supported tags

Tag	Example
`@param`	`---@param ply Player`
`@return`	`---@return boolean ok`
`@type`	`---@type Player`
`@class`	`---@class MyThing : Base`
`@field`	`---@field name string`
`@deprecated`	`---@deprecated use MyAddon.Other instead`

Type expressions

Form	Meaning
`Player`	A class, struct or primitive
`Entity\|nil`	A union
`Player?`	Shorthand for `Player\|nil`
`Entity[]`	An array
`table<string, Player>`	A map; the value type is what gets used
`fun(a: number)`	A function

A @param with no type is treated as documentation, not a type. Writing --- @param ply the player who did it will not create a type called the.

Casting with `---@type`

Inference can only work with what a value looks like at the point it’s created. Sometimes that’s nothing at all:

---@type Player
local target = nil

Without the annotation, target would infer as nil for its whole scope — there’s nothing in = nil to pull a class from. ---@type overrides that: whatever type you write becomes the type of target from here on, regardless of what the initialiser looked like. The same escape hatch narrows a value that came out too broad, like something pulled out of an untyped table:

local raw = someTable[key]

---@type Weapon
local weapon = raw

---@type only takes effect on a local declaration, and only for the first name when a statement declares several (local a, b = ...). It does nothing on a plain assignment (x = value) or a table field (self.target = value) — give those a type where they’re first declared with local instead.

Or annotate nothing

Parameters with no annotation are typed from the methods called on them.

local function canPlace(ply)
  return ply:IsAdmin()       -- IsAdmin exists only on Player -> Player
end

local function move(ent)
  ent:SetPos(ent:GetPos())   -- shared by many classes -> Entity
end

How the guess is made:

Collect the methods

Every : call on that parameter inside the function body.

Find the classes that have all of them

Searching the types people actually pass around first, so the ninety-odd panel classes cannot outvote Entity on a method they happen to share.

Prefer the common ancestor

When several match, the one the others inherit from wins — as long as it accounts for most of them.

Otherwise, stay quiet

An unrecognisable method set leaves the parameter as any rather than guessing.

An explicit ---@param always beats inference.

Which to use

Inference is free and covers most helper functions. Reach for annotations when:

the parameter is only passed through, never called on
the function is part of an API other people use
inference picked a base class and you want the specific one
you want the parameter documented in hover anyway

Get Started

Features

Formatting

Configuration

Annotations

Supported tags

Type expressions

Casting with `---@type`

Or annotate nothing

Which to use

​Annotations

​Supported tags

​Type expressions

​Casting with ---@type

​Or annotate nothing

​Which to use

Annotations

Supported tags

Type expressions

Casting with `---@type`

Or annotate nothing

Which to use