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