repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

opencode/skills/lua-annotations/references/annotations.md

Raw

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.