aboutsummaryrefslogtreecommitdiff
path: root/runtime
diff options
context:
space:
mode:
Diffstat (limited to 'runtime')
-rw-r--r--runtime/doc/develop.txt7
-rw-r--r--runtime/doc/diagnostic.txt3
-rw-r--r--runtime/doc/lsp.txt9
-rw-r--r--runtime/doc/lua.txt51
-rw-r--r--runtime/doc/treesitter.txt6
-rw-r--r--runtime/lua/vim/_inspector.lua2
-rw-r--r--runtime/lua/vim/_meta/builtin.lua4
-rw-r--r--runtime/lua/vim/filetype.lua1
-rw-r--r--runtime/lua/vim/loader.lua13
-rw-r--r--runtime/lua/vim/secure.lua2
-rw-r--r--runtime/lua/vim/treesitter.lua2
-rw-r--r--runtime/lua/vim/version.lua10
12 files changed, 104 insertions, 6 deletions
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 9dbdaec31c..ee7fa808f2 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -247,6 +247,10 @@ Docstring format:
- References are written as `[tag]`
- Use ``` for code samples.
Code samples can be annotated as `vim` or `lua`
+- Use `@since <api-level>` to note the |api-level| when the function became
+ "stable". If `<api-level>` is greater than the current stable release (or
+ 0), it is marked as "experimental".
+ - See scripts/util.lua for the mapping of api-level to Nvim version.
- Use `@nodoc` to prevent documentation generation.
- Use `@inlinedoc` to inline `@class` blocks into `@param` blocks.
E.g. >lua
@@ -271,7 +275,7 @@ Docstring format:
- {somefield}? (integer) Documentation
for some field
<
-- Files which has `@meta` are only used for typing and documentation.
+- Files declared as `@meta` are only used for typing and documentation (similar to "*.d.ts" typescript files).
Example: the help for |vim.paste()| is generated from a docstring decorating
vim.paste in runtime/lua/vim/_editor.lua like this: >
@@ -288,6 +292,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
--- end)()
--- ```
---
+ --- @since 12
--- @see |paste|
---
--- @param lines ...
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index bf931ed711..342947595e 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -733,6 +733,9 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
is_enabled({filter}) *vim.diagnostic.is_enabled()*
Check whether diagnostics are enabled.
+ Attributes: ~
+ Since: 0.10.0
+
Parameters: ~
• {filter} (`table?`) Optional filters |kwargs|, or `nil` for all.
• {ns_id}? (`integer`) Diagnostic namespace, or `nil` for
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index e06d400b63..47d8e190d4 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1673,6 +1673,9 @@ enable({enable}, {filter}) *vim.lsp.inlay_hint.enable()*
vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled())
<
+ Attributes: ~
+ Since: 0.10.0
+
Parameters: ~
• {enable} (`boolean?`) true/nil to enable, false to disable
• {filter} (`table?`) Optional filters |kwargs|, or `nil` for all.
@@ -1697,6 +1700,9 @@ get({filter}) *vim.lsp.inlay_hint.get()*
})
<
+ Attributes: ~
+ Since: 0.10.0
+
Parameters: ~
• {filter} (`table?`) Optional filters |kwargs|:
• {bufnr} (`integer?`)
@@ -1711,6 +1717,9 @@ get({filter}) *vim.lsp.inlay_hint.get()*
is_enabled({filter}) *vim.lsp.inlay_hint.is_enabled()*
Query whether inlay hint is enabled in the {filter}ed scope
+ Attributes: ~
+ Since: 0.10.0
+
Parameters: ~
• {filter} (`table?`) Optional filters |kwargs|, or `nil` for all.
• {bufnr} (`integer?`) Buffer number, or 0 for current
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 6269eb0c5b..fbd8da93bc 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1103,7 +1103,9 @@ vim.stricmp({a}, {b}) *vim.stricmp()*
lesser than {b}, respectively.
vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()*
- Attach to ui events, similar to |nvim_ui_attach()| but receive events as
+ WARNING: This feature is experimental/unstable.
+
+ Attach to |ui-events|, similar to |nvim_ui_attach()| but receive events as
Lua callback. Can be used to implement screen elements like popupmenu or
message handling in Lua.
@@ -1856,6 +1858,9 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()*
Can also be pretty-printed with `:Inspect!`. *:Inspect!*
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {bufnr} (`integer?`) defaults to the current buffer
• {row} (`integer?`) row to inspect, 0-based. Defaults to the row of
@@ -1889,6 +1894,9 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()*
Can also be shown with `:Inspect`. *:Inspect*
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {bufnr} (`integer?`) defaults to the current buffer
• {row} (`integer?`) row to inspect, 0-based. Defaults to the row of
@@ -2461,11 +2469,15 @@ vim.validate({opt}) *vim.validate()*
Lua module: vim.loader *vim.loader*
vim.loader.disable() *vim.loader.disable()*
+ WARNING: This feature is experimental/unstable.
+
Disables the experimental Lua module loader:
• removes the loaders
• adds the default Nvim loader
vim.loader.enable() *vim.loader.enable()*
+ WARNING: This feature is experimental/unstable.
+
Enables the experimental Lua module loader:
• overrides loadfile
• adds the Lua loader using the byte-compilation cache
@@ -2473,6 +2485,8 @@ vim.loader.enable() *vim.loader.enable()*
• removes the default Nvim loader
vim.loader.find({modname}, {opts}) *vim.loader.find()*
+ WARNING: This feature is experimental/unstable.
+
Finds Lua modules for the given module name.
Parameters: ~
@@ -2498,6 +2512,8 @@ vim.loader.find({modname}, {opts}) *vim.loader.find()*
returned for `modname="*"`
vim.loader.reset({path}) *vim.loader.reset()*
+ WARNING: This feature is experimental/unstable.
+
Resets the cache for the path, or all the paths if path is nil.
Parameters: ~
@@ -2767,6 +2783,9 @@ vim.filetype.get_option({filetype}, {option})
means |ftplugin| and |FileType| autocommands are only triggered once and
may not reflect later changes.
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {filetype} (`string`) Filetype
• {option} (`string`) Option name
@@ -3649,6 +3668,9 @@ vim.secure.read({path}) *vim.secure.read()*
be trusted. The user's choice is persisted in a trust database at
$XDG_STATE_HOME/nvim/trust.
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {path} (`string`) Path to a file to read.
@@ -3664,6 +3686,9 @@ vim.secure.trust({opts}) *vim.secure.trust()*
The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {opts} (`table`) A table with the following fields:
• {action} (`'allow'|'deny'|'remove'`) - `'allow'` to add a
@@ -3755,6 +3780,9 @@ vim.version.cmp({v1}, {v2}) *vim.version.cmp()*
• Per semver, build metadata is ignored when comparing two
otherwise-equivalent versions.
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {v1} (`vim.Version|number[]|string`) Version object.
• {v2} (`vim.Version|number[]|string`) Version to compare with `v1`.
@@ -3766,6 +3794,9 @@ vim.version.eq({v1}, {v2}) *vim.version.eq()*
Returns `true` if the given versions are equal. See |vim.version.cmp()|
for usage.
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {v1} (`vim.Version|number[]|string`)
• {v2} (`vim.Version|number[]|string`)
@@ -3776,6 +3807,9 @@ vim.version.eq({v1}, {v2}) *vim.version.eq()*
vim.version.ge({v1}, {v2}) *vim.version.ge()*
Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage.
+ Attributes: ~
+ Since: 0.10.0
+
Parameters: ~
• {v1} (`vim.Version|number[]|string`)
• {v2} (`vim.Version|number[]|string`)
@@ -3786,6 +3820,9 @@ vim.version.ge({v1}, {v2}) *vim.version.ge()*
vim.version.gt({v1}, {v2}) *vim.version.gt()*
Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage.
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {v1} (`vim.Version|number[]|string`)
• {v2} (`vim.Version|number[]|string`)
@@ -3805,6 +3842,9 @@ vim.version.last({versions}) *vim.version.last()*
vim.version.le({v1}, {v2}) *vim.version.le()*
Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage.
+ Attributes: ~
+ Since: 0.10.0
+
Parameters: ~
• {v1} (`vim.Version|number[]|string`)
• {v2} (`vim.Version|number[]|string`)
@@ -3815,6 +3855,9 @@ vim.version.le({v1}, {v2}) *vim.version.le()*
vim.version.lt({v1}, {v2}) *vim.version.lt()*
Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage.
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {v1} (`vim.Version|number[]|string`)
• {v2} (`vim.Version|number[]|string`)
@@ -3829,6 +3872,9 @@ vim.version.parse({version}, {opts}) *vim.version.parse()*
{ major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
<
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {version} (`string`) Version string to parse.
• {opts} (`table?`) Optional keyword arguments:
@@ -3869,6 +3915,9 @@ vim.version.range({spec}) *vim.version.range()*
print(vim.version.ge({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to))
<
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {spec} (`string`) Version range "spec"
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 0712f1f856..35192cc43d 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -854,6 +854,9 @@ foldexpr({lnum}) *vim.treesitter.foldexpr()*
vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
<
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {lnum} (`integer?`) Line number to calculate fold level for
@@ -1003,6 +1006,9 @@ inspect_tree({opts}) *vim.treesitter.inspect_tree()*
Can also be shown with `:InspectTree`. *:InspectTree*
+ Attributes: ~
+ Since: 0.9.0
+
Parameters: ~
• {opts} (`table?`) Optional options table with the following possible
keys:
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index 21dacbe41d..fccf4b8dbe 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -27,6 +27,7 @@ local defaults = {
---
---Can also be pretty-printed with `:Inspect!`. [:Inspect!]()
---
+---@since 11
---@param bufnr? integer defaults to the current buffer
---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor
@@ -145,6 +146,7 @@ end
---
---Can also be shown with `:Inspect`. [:Inspect]()
---
+---@since 11
---@param bufnr? integer defaults to the current buffer
---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor
---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 1a3f272290..13bd1c1294 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -248,7 +248,7 @@ function vim.schedule(fn) end
--- - If {callback} errors, the error is raised.
function vim.wait(time, callback, interval, fast_only) end
---- Attach to ui events, similar to |nvim_ui_attach()| but receive events
+--- Attach to |ui-events|, similar to |nvim_ui_attach()| but receive events
--- as Lua callback. Can be used to implement screen elements like
--- popupmenu or message handling in Lua.
---
@@ -282,6 +282,8 @@ function vim.wait(time, callback, interval, fast_only) end
--- end)
--- ```
---
+--- @since 0
+---
--- @param ns integer
--- @param options table<string, any>
--- @param callback fun()
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index e198d55160..d3910e26eb 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -2839,6 +2839,7 @@ end
--- Note: this uses |nvim_get_option_value()| but caches the result.
--- This means |ftplugin| and |FileType| autocommands are only
--- triggered once and may not reflect later changes.
+--- @since 11
--- @param filetype string Filetype
--- @param option string Option name
--- @return string|boolean|integer: Option value
diff --git a/runtime/lua/vim/loader.lua b/runtime/lua/vim/loader.lua
index 0211e8d4a1..e86d33bf53 100644
--- a/runtime/lua/vim/loader.lua
+++ b/runtime/lua/vim/loader.lua
@@ -289,6 +289,9 @@ function Loader.load(modpath, opts)
end
--- Finds Lua modules for the given module name.
+---
+--- @since 0
+---
---@param modname string Module name, or `"*"` to find the top-level modules instead
---@param opts? vim.loader.find.Opts Options for finding a module:
---@return vim.loader.ModuleInfo[]
@@ -377,8 +380,10 @@ function M.find(modname, opts)
return results
end
---- Resets the cache for the path, or all the paths
---- if path is nil.
+--- Resets the cache for the path, or all the paths if path is nil.
+---
+--- @since 0
+---
---@param path string? path to reset
function M.reset(path)
if path then
@@ -398,6 +403,8 @@ end
--- * adds the Lua loader using the byte-compilation cache
--- * adds the libs loader
--- * removes the default Nvim loader
+---
+--- @since 0
function M.enable()
if M.enabled then
return
@@ -421,6 +428,8 @@ end
--- Disables the experimental Lua module loader:
--- * removes the loaders
--- * adds the default Nvim loader
+---
+--- @since 0
function M.disable()
if not M.enabled then
return
diff --git a/runtime/lua/vim/secure.lua b/runtime/lua/vim/secure.lua
index 41a3d3ba25..266725cce2 100644
--- a/runtime/lua/vim/secure.lua
+++ b/runtime/lua/vim/secure.lua
@@ -41,6 +41,7 @@ end
--- trusted. The user's choice is persisted in a trust database at
--- $XDG_STATE_HOME/nvim/trust.
---
+---@since 11
---@see |:trust|
---
---@param path (string) Path to a file to read.
@@ -126,6 +127,7 @@ end
---
--- The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
---
+---@since 11
---@param opts vim.trust.opts
---@return boolean success true if operation was successful
---@return string msg full path if operation was successful, else error message
diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua
index de52685220..ed7d31e1f7 100644
--- a/runtime/lua/vim/treesitter.lua
+++ b/runtime/lua/vim/treesitter.lua
@@ -447,6 +447,7 @@ end
---
--- Can also be shown with `:InspectTree`. [:InspectTree]()
---
+---@since 11
---@param opts table|nil Optional options table with the following possible keys:
--- - lang (string|nil): The language of the source buffer. If omitted, detect
--- from the filetype of the source buffer.
@@ -470,6 +471,7 @@ end
--- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
--- ```
---
+---@since 11
---@param lnum integer|nil Line number to calculate fold level for
---@return string
function M.foldexpr(lnum)
diff --git a/runtime/lua/vim/version.lua b/runtime/lua/vim/version.lua
index 7c8823bd72..d64ef98d2d 100644
--- a/runtime/lua/vim/version.lua
+++ b/runtime/lua/vim/version.lua
@@ -276,6 +276,7 @@ end
--- ```
---
--- @see # https://github.com/npm/node-semver#ranges
+--- @since 11
---
--- @param spec string Version range "spec"
--- @return vim.VersionRange?
@@ -375,6 +376,7 @@ end
--- ```
---
--- @note Per semver, build metadata is ignored when comparing two otherwise-equivalent versions.
+--- @since 11
---
---@param v1 vim.Version|number[]|string Version object.
---@param v2 vim.Version|number[]|string Version to compare with `v1`.
@@ -392,6 +394,7 @@ function M.cmp(v1, v2)
end
---Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage.
+---@since 11
---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string
---@return boolean
@@ -400,6 +403,7 @@ function M.eq(v1, v2)
end
---Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage.
+---@since 12
---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string
---@return boolean
@@ -408,6 +412,7 @@ function M.le(v1, v2)
end
---Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage.
+---@since 11
---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string
---@return boolean
@@ -416,6 +421,7 @@ function M.lt(v1, v2)
end
---Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage.
+---@since 12
---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string
---@return boolean
@@ -424,6 +430,7 @@ function M.ge(v1, v2)
end
---Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage.
+---@since 11
---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string
---@return boolean
@@ -438,7 +445,8 @@ end
--- { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
--- ```
---
---- @see # https://semver.org/spec/v2.0.0.html
+---@see # https://semver.org/spec/v2.0.0.html
+---@since 11
---
---@param version string Version string to parse.
---@param opts table|nil Optional keyword arguments:
generated by cgit (git 2.34.1) at 2025-04-29 08:11:33 +0000