Annotation Syntax - EmmyLua Analyzer

Basic Syntax

All EmmyLua annotations start with the ---@ prefix (three dashes followed by @). This distinguishes them from regular comments:

-- This is a regular comment

--- This is a documentation comment (LuaDoc style)

---@type string
-- This is an EmmyLua annotation

Annotation Format

The general structure of an annotation is:

---@annotation_name parameters description

Each part serves a specific purpose:

---@ - The annotation prefix
annotation_name - The type of annotation (class, param, return, etc.)
parameters - Required parameters for the annotation
description - Optional human-readable description

Comment Format

Single-Line Annotations

Most annotations fit on a single line:

---@type string
local name = "John"

---@param x number
---@param y number
---@return number
function add(x, y)
    return x + y
end

Multi-Line Annotations

Some annotations span multiple lines. Each line must start with ---@ or ---| :

---@alias HTTPMethod
---| 'GET'     # HTTP GET request
---| 'POST'    # HTTP POST request
---| 'PUT'     # HTTP PUT request
---| 'DELETE'  # HTTP DELETE request

---@class User
---@field id number User ID
---@field name string Username
---@field email string Email address
---@field role 'admin'|'user'|'guest' User role

The ---| prefix (three dashes, pipe, space) is used for enumeration values in @alias annotations.

Annotation Placement

Annotations must be placed immediately before the item they describe, with no blank lines in between.

Annotating Variables

Place the annotation directly above the variable:

---@type string
local userName = "John"

---@type number
local userAge = 25

---@type {name: string, age: number}
local user = {name = "John", age = 25}

Annotating Functions

Place annotations directly above the function definition:

---@param name string Username
---@param age number User age
---@return table User object
function createUser(name, age)
    return {name = name, age = age}
end

Annotating Classes

Define the class structure, then the implementation:

---@class Animal
---@field name string Animal name
---@field species string Species
---@field age number Age in years
local Animal = {}

---@param name string
---@param species string
---@return Animal
function Animal.new(name, species)
    return setmetatable({
        name = name,
        species = species,
        age = 0
    }, {__index = Animal})
end

Annotating Fields and Methods

---@class Database
local Database = {}

---@type string
Database.host = "localhost"

---@type number
Database.port = 5432

---@param query string SQL query
---@return table[] Result rows
function Database:execute(query)
    -- Implementation
end

Annotation Structure

Syntax Notation Symbols

The documentation uses these symbols to describe annotation syntax:

Symbol	Meaning	Example
`<name>`	Required placeholder	`---@param <param_name> <type>`
`[value]`	Optional item	`---@param name string [description]`
`[value...]`	Optional and repeatable	`---@class Name [: Parent...]`
`value1 \| value2`	Choice (either/or)	`'GET' \| 'POST'`
`<type[\|type...]>`	Type expression with unions	`string \| number`
`[(modifier)]`	Optional modifier	`---@class (exact) Point`
`#`	Comment marker	`---\| 'GET' # Description`

Required vs Optional Parameters

Some annotation parameters are required, others are optional:

-- @type requires only the type
---@type string

-- @param requires name and type, description is optional
---@param name string
---@param age number User age in years

-- @class requires name, parent classes are optional
---@class User
---@class Admin : User
---@class SuperAdmin : Admin, Auditable

Type Expressions

Type expressions can be simple or complex:

-- Simple types
---@type string
---@type number
---@type boolean

-- Union types
---@type string | number
---@type string | nil

-- Array types
---@type string[]
---@type number[]

-- Table types
---@type table<string, number>
---@type table<number, string>

-- Function types
---@type fun(x: number): string
---@type fun(name: string, age: number): User

-- Tuple types
---@type [string, number, boolean]

-- Table literal types
---@type {name: string, age: number}

-- Complex combinations
---@type table<string, fun(x: number): boolean> | nil

Common Patterns

Pattern 1: Variable Type Declaration

---@type <type_expression>
local variableName = value

Example:

---@type string
local userName = "John"

---@type number[]
local scores = {95, 87, 92}

Pattern 2: Function Documentation

---@param <param_name> <type> [description]
---@param <param_name> <type> [description]
---@return <type> [description]
function functionName(param1, param2)
    -- Implementation
end

Example:

---@param x number First number
---@param y number Second number
---@return number Sum of x and y
function add(x, y)
    return x + y
end

Pattern 3: Class Definition

---@class <ClassName> [: ParentClass]
---@field <field_name> <type> [description]
---@field <field_name> <type> [description]
local ClassName = {}

Example:

---@class User
---@field id number User ID
---@field name string Username
---@field email string Email address
local User = {}

Pattern 4: Type Alias

---@alias <AliasName> <type_expression>

Example:

---@alias ID number
---@alias Callback fun(error: string?, result: any?): nil
---@alias Status 'pending'|'running'|'completed'|'failed'

Pattern 5: Enumeration

---@alias <EnumName>
---| '<value1>' [# description]
---| '<value2>' [# description]
---| '<value3>' [# description]

Example:

---@alias LogLevel
---| 'debug'   # Debug messages
---| 'info'    # Informational messages
---| 'warn'    # Warning messages
---| 'error'   # Error messages

Pattern 6: Generic Function

---@generic <T>
---@param <param> <T>
---@return <T>
function functionName(param)
    -- Implementation
end

Example:

---@generic T
---@param items T[]
---@param predicate fun(item: T): boolean
---@return T[]
function filter(items, predicate)
    local result = {}
    for _, item in ipairs(items) do
        if predicate(item) then
            table.insert(result, item)
        end
    end
    return result
end

Annotation Chaining

Multiple annotations can be chained together to provide complete type information:

Class with Fields and Methods

---@class Calculator
---@field value number Current value
---@field history number[] Calculation history
local Calculator = {}

---@param initial number Starting value
---@return Calculator
function Calculator.new(initial)
    return setmetatable({
        value = initial,
        history = {initial}
    }, {__index = Calculator})
end

---@param x number Number to add
---@return Calculator self For method chaining
function Calculator:add(x)
    self.value = self.value + x
    table.insert(self.history, self.value)
    return self
end

Function with Multiple Parameters and Returns

---@param url string Request URL
---@param method 'GET'|'POST'|'PUT'|'DELETE' HTTP method
---@param headers? table<string, string> Optional headers
---@param body? string Optional request body
---@return boolean success Whether request succeeded
---@return string? response Response body if successful
---@return string? error Error message if failed
function httpRequest(url, method, headers, body)
    -- Implementation
end

Generic Class with Constraints

---@class Container<T>
---@field private items T[]
---@field capacity number
local Container = {}

---@generic T
---@param capacity number Maximum number of items
---@return Container<T>
function Container.new(capacity)
    return {
        items = {},
        capacity = capacity
    }
end

---@generic T
---@param self Container<T>
---@param item T
---@return boolean success Whether item was added
function Container:add(item)
    if #self.items < self.capacity then
        table.insert(self.items, item)
        return true
    end
    return false
end

Annotation Formats: EmmyLua vs LuaCATS

Both formats are supported and can be used interchangeably:

EmmyLua Format

The original format with ---@ prefix:

---@class Vector
---@field x number
---@field y number
local Vector = {}

---@param x number
---@param y number
---@return Vector
function Vector.new(x, y)
    return setmetatable({x = x, y = y}, {__index = Vector})
end

---@return number
function Vector:magnitude()
    return math.sqrt(self.x^2 + self.y^2)
end

LuaCATS Format

Documentation-focused with descriptive text:

--- Vector class for 2D coordinates
---@class Vector
---@field x number X coordinate
---@field y number Y coordinate
local Vector = {}

--- Create a new vector
---@param x number X coordinate
---@param y number Y coordinate
---@return Vector A new vector instance
function Vector.new(x, y)
    return setmetatable({x = x, y = y}, {__index = Vector})
end

--- Calculate the magnitude of the vector
---@return number The magnitude
function Vector:magnitude()
    return math.sqrt(self.x^2 + self.y^2)
end

You can mix both formats in the same project, but maintaining consistency improves readability.

Best Practices

1. Be Consistent

Choose a style and stick to it throughout your project:

-- Good: Consistent formatting
---@param name string
---@param age number
---@return User

-- Avoid: Inconsistent spacing
---@param name   string
---@param age number
---@return    User

2. Document Public APIs

Always annotate public functions and classes:

-- Public API - fully documented
---@class Database
---@field host string
---@field port number

---@param config {host: string, port: number}
---@return Database
function Database.new(config)
    -- Implementation
end

-- Private helper - can be less formal
local function parseConnectionString(str)
    -- Implementation
end

3. Use Descriptive Names

Choose clear, self-documenting parameter names:

-- Good
---@param userName string
---@param userAge number
function createUser(userName, userAge)
end

-- Less clear
---@param n string
---@param a number
function createUser(n, a)
end

4. Add Descriptions for Complex Types

---@param options {timeout: number, retries: number, backoff: boolean} Configuration options for the request. Timeout in seconds, retries is the max number of attempts, backoff enables exponential backoff
function httpRequest(url, options)
end

-- Good: Grouped by purpose
---@class User
---@field id number
---@field name string
---@field email string
---@field createdAt number
---@field updatedAt number

-- Less organized: Mixed ordering
---@class User
---@field name string
---@field id number
---@field updatedAt number
---@field email string
---@field createdAt number

Next Steps

Now that you understand annotation syntax, explore specific annotation types:

Type Annotations

Learn about @type and type expressions

Class Definitions

Define classes with @class and @field

Function Parameters

Document parameters with @param

Return Values

Specify return types with @return

Type Aliases

Create reusable types with @alias

Generics

Use generic types with @generic

Overview

Type Annotations

Function Annotations

Advanced Annotations

​Basic Syntax

​Annotation Format

​Comment Format

​Single-Line Annotations

​Multi-Line Annotations

​Annotation Placement

​Annotating Variables

​Annotating Functions

​Annotating Classes

​Annotating Fields and Methods

​Annotation Structure

​Syntax Notation Symbols

​Required vs Optional Parameters

​Type Expressions

​Common Patterns

​Pattern 1: Variable Type Declaration

​Pattern 2: Function Documentation

​Pattern 3: Class Definition

​Pattern 4: Type Alias

​Pattern 5: Enumeration

​Pattern 6: Generic Function

​Annotation Chaining

​Class with Fields and Methods

​Function with Multiple Parameters and Returns

​Generic Class with Constraints

​Annotation Formats: EmmyLua vs LuaCATS

​EmmyLua Format

​LuaCATS Format

​Best Practices

​1. Be Consistent

​2. Document Public APIs

​3. Use Descriptive Names

​4. Add Descriptions for Complex Types

​5. Group Related Annotations

​Next Steps

Type Annotations

Class Definitions

Function Parameters

Return Values

Type Aliases

Generics

Build docs developers (and LLMs) love

Basic Syntax

Annotation Format

Comment Format

Single-Line Annotations

Multi-Line Annotations

Annotation Placement

Annotating Variables

Annotating Functions

Annotating Classes

Annotating Fields and Methods

Annotation Structure

Syntax Notation Symbols

Required vs Optional Parameters

Type Expressions

Common Patterns

Pattern 1: Variable Type Declaration

Pattern 2: Function Documentation

Pattern 3: Class Definition

Pattern 4: Type Alias

Pattern 5: Enumeration

Pattern 6: Generic Function

Annotation Chaining

Class with Fields and Methods

Function with Multiple Parameters and Returns

Generic Class with Constraints

Annotation Formats: EmmyLua vs LuaCATS

EmmyLua Format

LuaCATS Format

Best Practices

1. Be Consistent

2. Document Public APIs

3. Use Descriptive Names

4. Add Descriptions for Complex Types

5. Group Related Annotations

Next Steps