LuaCATS Annotation Reference
Complete table of all LuaLS/LuaCATS annotations. Neovim-specific annotations
marked with (N).
Type Definition Annotations
@alias — Type Alias
Define a named type alias, often a union.
--- @alias vim._watch.Callback fun(path: string, change_type: vim._watch.FileChangeType)
--- @alias vim.api.keyset.events
--- | 'BufAdd'
--- | 'BufCreate'
--- | 'BufDelete'
@class — Class/Struct Definition
Define a compound type with named fields.
--- @class vim.api.keyset.win_config
--- @field external? boolean
--- @field width? integer
--- @class vim.fn.winsaveview.ret: vim.fn.winrestview.dict
--- @field col integer
--- @class (exact) MyConfig -- exact = no field injection
--- @class (private) vim.var_accessor -- private class
@enum — Runtime Enum
Define a set of named constant values.
--- @enum vim._watch.FileChangeType
M.FileChangeType = {
Created = 1,
Changed = 2,
Deleted = 3,
}
Use @alias for type-only unions. Use @enum for runtime constants.
@field — Class Field
Define a field on a class.
--- @field name string
--- @field id? integer
--- @field items? string[]
--- @field callback? fun(err: string, data: string)
--- @field nr? integer|'$'
--- @field [string] any -- index signature: any string key
--- @field [integer] vim.var_accessor -- numeric index signature
@type — Variable Type
Type a variable directly without a class.
--- @type vim.NIL
vim.NIL = ...
--- @type LazyPlugin[]
M.to_clean = {}
--- @type string
M.me = nil
@generic — Generic Type Parameter
Declare type parameters for generic functions.
--- @generic T
--- @param list T[]
--- @return T
Function Documentation Annotations
@param — Function Parameter
--- @param buffer integer Buffer id, or 0 for current buffer
--- @param opts vim.api.keyset.set_extmark Optional parameters.
--- @param opts? table -- optional (equivalent form)
--- @param ... any -- variadic
@return — Return Value
--- @return integer # Id of the created extmark
--- @return string[] # List of files
--- @return boolean # true if found
Named returns:
--- @return boolean ok
--- @return nil|-1|-2 status
Optional return:
--- @return string?
Tuple return:
--- @return [integer, integer]
--- @return [integer, integer, vim.api.keyset.extmark_details?]
@overload — Function Overload
--- @overload fun(self: TSNode, include_bytes: true): integer, integer, integer, integer, integer, integer
--- @overload fun(self: TSNode, include_bytes?: false): integer, integer, integer, integer
function TSNode:range(include_bytes) end
@async — Async Function
--- @async
Visibility Annotations
@private — Private Visibility
--- @private
function vim._on_key(buf, typed_buf) end
@package — Package Visibility
--- @package
@protected — Protected Visibility
--- @protected
@meta — Meta/File Marker
Mark a file as type-definition-only.
--- @meta _
error('Cannot require a meta file')
@nodoc — Suppress Documentation (N)
Tells Neovim's doc generator to skip.
--- @nodoc
vim.log = { ... }
Control Annotations
@deprecated — Mark Deprecated
--- @deprecated
function vim.api.nvim_buf_add_highlight(...) end
@nodiscard — Warn on Unused Result
--- @nodiscard
function M.important() end
@diagnostic — Control LuaLS Warnings
--- @diagnostic disable: undefined-doc-name
--- @diagnostic disable-next-line: unused-function
--- @diagnostic disable-next-line: undefined-doc-param
--- @diagnostic disable-next-line: inject-field
@cast — Type Assertion
--- @cast parsed nvim.luacats.Class
@version — Version Marker
--- @version 0.10
Reference Annotations
@see — Cross-Reference
--- @see vim.api.nvim_buf_detach
--- @see `:help api-buffer-updates-lua`
--- @see |vim.print()|
--- @see https://github.com/kikito/inspect.lua
Other Annotations
@module — Module Declaration
--- @module "nvim-treesitter"
@source — Source Attribution
--- @source https://example.com/original
@operator — Operator Definition
--- @operator
@inlinedoc — Inline Doc (N)
Internal Neovim mechanism for inline doc blocks.
@note — Note Callout (N)
---@note {fn} will be removed on error.
@brief — Module Description (N)
--- @brief A treesitter node represents...
@since — Version Added (N)
--- @since 0
Inline Annotations
---@type — Inline Variable Type
local x = 42 ---@type number
--[[@as]] — Inline Type Cast
--[[@as string]]
local x = something
Quick Lookup Table
| Annotation |
Used On |
Purpose |
@alias |
class/property |
Named type alias, often union |
@async |
function |
Mark async function |
@cast |
expression |
Type assertion |
@class |
class/property |
Define class/struct type |
@deprecated |
function/class |
Mark as deprecated |
@diagnostic |
file/line |
Control LuaLS warnings |
@enum |
class |
Runtime enum (constants) |
@field |
class |
Define class field |
@generic |
function |
Generic type parameter |
@meta |
file |
Mark type-only file |
@module |
file |
Declare module |
@nodiscard |
function |
Warn if return unused |
@nodoc |
any (N) |
Suppress from docs |
@note |
any (N) |
Note callout |
@operator |
class |
Define operator |
@overload |
function |
Alternative signatures |
@package |
function/field |
Package visibility |
@param |
function |
Document parameter |
@private |
function/field |
Private visibility |
@protected |
function/field |
Protected visibility |
@return |
function |
Document return value |
@see |
any |
Cross-reference |
@since |
any (N) |
Version added |
@source |
any |
Source attribution |
@type |
variable |
Type of variable |
@version |
any |
Version marker |
---@type |
inline |
Inline variable type |
--[[@as]] |
inline |
Inline type cast |
@brief |
module (N) |
Module-level description |
@inlinedoc |
(N) |
Inline doc block |
(N) = Neovim-specific extension to LuaCATS.
Markdown source
# LuaCATS Annotation Reference
Complete table of all LuaLS/LuaCATS annotations. Neovim-specific annotations
marked with `(N)`.
## Type Definition Annotations
### @alias — Type Alias
Define a named type alias, often a union.
```lua
--- @alias vim._watch.Callback fun(path: string, change_type: vim._watch.FileChangeType)
--- @alias vim.api.keyset.events
--- | 'BufAdd'
--- | 'BufCreate'
--- | 'BufDelete'
```
### @class — Class/Struct Definition
Define a compound type with named fields.
```lua
--- @class vim.api.keyset.win_config
--- @field external? boolean
--- @field width? integer
--- @class vim.fn.winsaveview.ret: vim.fn.winrestview.dict
--- @field col integer
--- @class (exact) MyConfig -- exact = no field injection
--- @class (private) vim.var_accessor -- private class
```
### @enum — Runtime Enum
Define a set of named constant values.
```lua
--- @enum vim._watch.FileChangeType
M.FileChangeType = {
Created = 1,
Changed = 2,
Deleted = 3,
}
```
Use `@alias` for type-only unions. Use `@enum` for runtime constants.
### @field — Class Field
Define a field on a class.
```lua
--- @field name string
--- @field id? integer
--- @field items? string[]
--- @field callback? fun(err: string, data: string)
--- @field nr? integer|'$'
--- @field [string] any -- index signature: any string key
--- @field [integer] vim.var_accessor -- numeric index signature
```
### @type — Variable Type
Type a variable directly without a class.
```lua
--- @type vim.NIL
vim.NIL = ...
--- @type LazyPlugin[]
M.to_clean = {}
--- @type string
M.me = nil
```
### @generic — Generic Type Parameter
Declare type parameters for generic functions.
```lua
--- @generic T
--- @param list T[]
--- @return T
```
---
## Function Documentation Annotations
### @param — Function Parameter
```lua
--- @param buffer integer Buffer id, or 0 for current buffer
--- @param opts vim.api.keyset.set_extmark Optional parameters.
--- @param opts? table -- optional (equivalent form)
--- @param ... any -- variadic
```
### @return — Return Value
```lua
--- @return integer # Id of the created extmark
--- @return string[] # List of files
--- @return boolean # true if found
```
**Named returns:**
```lua
--- @return boolean ok
--- @return nil|-1|-2 status
```
**Optional return:**
```lua
--- @return string?
```
**Tuple return:**
```lua
--- @return [integer, integer]
--- @return [integer, integer, vim.api.keyset.extmark_details?]
```
### @overload — Function Overload
```lua
--- @overload fun(self: TSNode, include_bytes: true): integer, integer, integer, integer, integer, integer
--- @overload fun(self: TSNode, include_bytes?: false): integer, integer, integer, integer
function TSNode:range(include_bytes) end
```
### @async — Async Function
```lua
--- @async
```
---
## Visibility Annotations
### @private — Private Visibility
```lua
--- @private
function vim._on_key(buf, typed_buf) end
```
### @package — Package Visibility
```lua
--- @package
```
### @protected — Protected Visibility
```lua
--- @protected
```
### @meta — Meta/File Marker
Mark a file as type-definition-only.
```lua
--- @meta _
error('Cannot require a meta file')
```
### @nodoc — Suppress Documentation (N)
Tells Neovim's doc generator to skip.
```lua
--- @nodoc
vim.log = { ... }
```
---
## Control Annotations
### @deprecated — Mark Deprecated
```lua
--- @deprecated
function vim.api.nvim_buf_add_highlight(...) end
```
### @nodiscard — Warn on Unused Result
```lua
--- @nodiscard
function M.important() end
```
### @diagnostic — Control LuaLS Warnings
```lua
--- @diagnostic disable: undefined-doc-name
--- @diagnostic disable-next-line: unused-function
--- @diagnostic disable-next-line: undefined-doc-param
--- @diagnostic disable-next-line: inject-field
```
### @cast — Type Assertion
```lua
--- @cast parsed nvim.luacats.Class
```
### @version — Version Marker
```lua
--- @version 0.10
```
---
## Reference Annotations
### @see — Cross-Reference
```lua
--- @see vim.api.nvim_buf_detach
--- @see `:help api-buffer-updates-lua`
--- @see |vim.print()|
--- @see https://github.com/kikito/inspect.lua
```
---
## Other Annotations
### @module — Module Declaration
```lua
--- @module "nvim-treesitter"
```
### @source — Source Attribution
```lua
--- @source https://example.com/original
```
### @operator — Operator Definition
```lua
--- @operator
```
### @inlinedoc — Inline Doc (N)
Internal Neovim mechanism for inline doc blocks.
### @note — Note Callout (N)
```lua
---@note {fn} will be removed on error.
```
### @brief — Module Description (N)
```lua
--- @brief A treesitter node represents...
```
### @since — Version Added (N)
```lua
--- @since 0
```
---
## Inline Annotations
### ---@type — Inline Variable Type
```lua
local x = 42 ---@type number
```
### --[[@as]] — Inline Type Cast
```lua
--[[@as string]]
local x = something
```
---
## Quick Lookup Table
| Annotation | Used On | Purpose |
| ------------- | -------------- | ----------------------------- |
| `@alias` | class/property | Named type alias, often union |
| `@async` | function | Mark async function |
| `@cast` | expression | Type assertion |
| `@class` | class/property | Define class/struct type |
| `@deprecated` | function/class | Mark as deprecated |
| `@diagnostic` | file/line | Control LuaLS warnings |
| `@enum` | class | Runtime enum (constants) |
| `@field` | class | Define class field |
| `@generic` | function | Generic type parameter |
| `@meta` | file | Mark type-only file |
| `@module` | file | Declare module |
| `@nodiscard` | function | Warn if return unused |
| `@nodoc` | any (N) | Suppress from docs |
| `@note` | any (N) | Note callout |
| `@operator` | class | Define operator |
| `@overload` | function | Alternative signatures |
| `@package` | function/field | Package visibility |
| `@param` | function | Document parameter |
| `@private` | function/field | Private visibility |
| `@protected` | function/field | Protected visibility |
| `@return` | function | Document return value |
| `@see` | any | Cross-reference |
| `@since` | any (N) | Version added |
| `@source` | any | Source attribution |
| `@type` | variable | Type of variable |
| `@version` | any | Version marker |
| `---@type` | inline | Inline variable type |
| `--[[@as]]` | inline | Inline type cast |
| `@brief` | module (N) | Module-level description |
| `@inlinedoc` | (N) | Inline doc block |
**(N)** = Neovim-specific extension to LuaCATS.