docs: render @since versions, 0 means experimental #30649

An implication of this current approach is that `NVIM_API_LEVEL` should be
bumped when a new Lua function is added.

TODO(future): add a lint check which requires `@since` on all new functions.

ref #25416
This commit is contained in:
Justin M. Keyes 2024-10-04 02:13:31 -07:00 committed by GitHub
parent f62728cd80
commit b45c50f314
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
16 changed files with 156 additions and 33 deletions

View File

@ -247,6 +247,10 @@ Docstring format:
- References are written as `[tag]` - References are written as `[tag]`
- Use ``` for code samples. - Use ``` for code samples.
Code samples can be annotated as `vim` or `lua` 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 `@nodoc` to prevent documentation generation.
- Use `@inlinedoc` to inline `@class` blocks into `@param` blocks. - Use `@inlinedoc` to inline `@class` blocks into `@param` blocks.
E.g. >lua E.g. >lua
@ -271,7 +275,7 @@ Docstring format:
- {somefield}? (integer) Documentation - {somefield}? (integer) Documentation
for some field 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 Example: the help for |vim.paste()| is generated from a docstring decorating
vim.paste in runtime/lua/vim/_editor.lua like this: > 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)() --- end)()
--- ``` --- ```
--- ---
--- @since 12
--- @see |paste| --- @see |paste|
--- ---
--- @param lines ... --- @param lines ...

View File

@ -733,6 +733,9 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
is_enabled({filter}) *vim.diagnostic.is_enabled()* is_enabled({filter}) *vim.diagnostic.is_enabled()*
Check whether diagnostics are enabled. Check whether diagnostics are enabled.
Attributes: ~
Since: 0.10.0
Parameters: ~ Parameters: ~
• {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all.
• {ns_id}? (`integer`) Diagnostic namespace, or `nil` for • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for

View File

@ -1673,6 +1673,9 @@ enable({enable}, {filter}) *vim.lsp.inlay_hint.enable()*
vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled()) vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled())
< <
Attributes: ~
Since: 0.10.0
Parameters: ~ Parameters: ~
• {enable} (`boolean?`) true/nil to enable, false to disable • {enable} (`boolean?`) true/nil to enable, false to disable
• {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. • {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: ~ Parameters: ~
• {filter} (`table?`) Optional filters |kwargs|: • {filter} (`table?`) Optional filters |kwargs|:
• {bufnr} (`integer?`) • {bufnr} (`integer?`)
@ -1711,6 +1717,9 @@ get({filter}) *vim.lsp.inlay_hint.get()*
is_enabled({filter}) *vim.lsp.inlay_hint.is_enabled()* is_enabled({filter}) *vim.lsp.inlay_hint.is_enabled()*
Query whether inlay hint is enabled in the {filter}ed scope Query whether inlay hint is enabled in the {filter}ed scope
Attributes: ~
Since: 0.10.0
Parameters: ~ Parameters: ~
• {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all.
• {bufnr} (`integer?`) Buffer number, or 0 for current • {bufnr} (`integer?`) Buffer number, or 0 for current

View File

@ -1103,7 +1103,9 @@ vim.stricmp({a}, {b}) *vim.stricmp()*
lesser than {b}, respectively. lesser than {b}, respectively.
vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()* 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 Lua callback. Can be used to implement screen elements like popupmenu or
message handling in Lua. 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!* Can also be pretty-printed with `:Inspect!`. *:Inspect!*
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {bufnr} (`integer?`) defaults to the current buffer • {bufnr} (`integer?`) defaults to the current buffer
• {row} (`integer?`) row to inspect, 0-based. Defaults to the row of • {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* Can also be shown with `:Inspect`. *:Inspect*
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {bufnr} (`integer?`) defaults to the current buffer • {bufnr} (`integer?`) defaults to the current buffer
• {row} (`integer?`) row to inspect, 0-based. Defaults to the row of • {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* Lua module: vim.loader *vim.loader*
vim.loader.disable() *vim.loader.disable()* vim.loader.disable() *vim.loader.disable()*
WARNING: This feature is experimental/unstable.
Disables the experimental Lua module loader: Disables the experimental Lua module loader:
• removes the loaders • removes the loaders
• adds the default Nvim loader • adds the default Nvim loader
vim.loader.enable() *vim.loader.enable()* vim.loader.enable() *vim.loader.enable()*
WARNING: This feature is experimental/unstable.
Enables the experimental Lua module loader: Enables the experimental Lua module loader:
• overrides loadfile • overrides loadfile
• adds the Lua loader using the byte-compilation cache • adds the Lua loader using the byte-compilation cache
@ -2473,6 +2485,8 @@ vim.loader.enable() *vim.loader.enable()*
• removes the default Nvim loader • removes the default Nvim loader
vim.loader.find({modname}, {opts}) *vim.loader.find()* vim.loader.find({modname}, {opts}) *vim.loader.find()*
WARNING: This feature is experimental/unstable.
Finds Lua modules for the given module name. Finds Lua modules for the given module name.
Parameters: ~ Parameters: ~
@ -2498,6 +2512,8 @@ vim.loader.find({modname}, {opts}) *vim.loader.find()*
returned for `modname="*"` returned for `modname="*"`
vim.loader.reset({path}) *vim.loader.reset()* 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. Resets the cache for the path, or all the paths if path is nil.
Parameters: ~ Parameters: ~
@ -2767,6 +2783,9 @@ vim.filetype.get_option({filetype}, {option})
means |ftplugin| and |FileType| autocommands are only triggered once and means |ftplugin| and |FileType| autocommands are only triggered once and
may not reflect later changes. may not reflect later changes.
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {filetype} (`string`) Filetype • {filetype} (`string`) Filetype
• {option} (`string`) Option name • {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 be trusted. The user's choice is persisted in a trust database at
$XDG_STATE_HOME/nvim/trust. $XDG_STATE_HOME/nvim/trust.
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {path} (`string`) Path to a file to read. • {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. The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {opts} (`table`) A table with the following fields: • {opts} (`table`) A table with the following fields:
• {action} (`'allow'|'deny'|'remove'`) - `'allow'` to add a • {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 • Per semver, build metadata is ignored when comparing two
otherwise-equivalent versions. otherwise-equivalent versions.
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {v1} (`vim.Version|number[]|string`) Version object. • {v1} (`vim.Version|number[]|string`) Version object.
• {v2} (`vim.Version|number[]|string`) Version to compare with `v1`. • {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()| Returns `true` if the given versions are equal. See |vim.version.cmp()|
for usage. for usage.
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {v1} (`vim.Version|number[]|string`) • {v1} (`vim.Version|number[]|string`)
• {v2} (`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()* vim.version.ge({v1}, {v2}) *vim.version.ge()*
Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage. Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage.
Attributes: ~
Since: 0.10.0
Parameters: ~ Parameters: ~
• {v1} (`vim.Version|number[]|string`) • {v1} (`vim.Version|number[]|string`)
• {v2} (`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()* vim.version.gt({v1}, {v2}) *vim.version.gt()*
Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage. Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage.
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {v1} (`vim.Version|number[]|string`) • {v1} (`vim.Version|number[]|string`)
• {v2} (`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()* vim.version.le({v1}, {v2}) *vim.version.le()*
Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage. Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage.
Attributes: ~
Since: 0.10.0
Parameters: ~ Parameters: ~
• {v1} (`vim.Version|number[]|string`) • {v1} (`vim.Version|number[]|string`)
• {v2} (`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()* vim.version.lt({v1}, {v2}) *vim.version.lt()*
Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage. Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage.
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {v1} (`vim.Version|number[]|string`) • {v1} (`vim.Version|number[]|string`)
• {v2} (`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" } { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" }
< <
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {version} (`string`) Version string to parse. • {version} (`string`) Version string to parse.
• {opts} (`table?`) Optional keyword arguments: • {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)) print(vim.version.ge({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to))
< <
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {spec} (`string`) Version range "spec" • {spec} (`string`) Version range "spec"

View File

@ -854,6 +854,9 @@ foldexpr({lnum}) *vim.treesitter.foldexpr()*
vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()' vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
< <
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {lnum} (`integer?`) Line number to calculate fold level for • {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* Can also be shown with `:InspectTree`. *:InspectTree*
Attributes: ~
Since: 0.9.0
Parameters: ~ Parameters: ~
• {opts} (`table?`) Optional options table with the following possible • {opts} (`table?`) Optional options table with the following possible
keys: keys:

View File

@ -27,6 +27,7 @@ local defaults = {
--- ---
---Can also be pretty-printed with `:Inspect!`. [:Inspect!]() ---Can also be pretty-printed with `:Inspect!`. [:Inspect!]()
--- ---
---@since 11
---@param bufnr? integer defaults to the current buffer ---@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 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 ---@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]() ---Can also be shown with `:Inspect`. [:Inspect]()
--- ---
---@since 11
---@param bufnr? integer defaults to the current buffer ---@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 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 ---@param col? integer col to inspect, 0-based. Defaults to the col of the current cursor

View File

@ -248,7 +248,7 @@ function vim.schedule(fn) end
--- - If {callback} errors, the error is raised. --- - If {callback} errors, the error is raised.
function vim.wait(time, callback, interval, fast_only) end 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 --- as Lua callback. Can be used to implement screen elements like
--- popupmenu or message handling in Lua. --- popupmenu or message handling in Lua.
--- ---
@ -282,6 +282,8 @@ function vim.wait(time, callback, interval, fast_only) end
--- end) --- end)
--- ``` --- ```
--- ---
--- @since 0
---
--- @param ns integer --- @param ns integer
--- @param options table<string, any> --- @param options table<string, any>
--- @param callback fun() --- @param callback fun()

View File

@ -2839,6 +2839,7 @@ end
--- Note: this uses |nvim_get_option_value()| but caches the result. --- Note: this uses |nvim_get_option_value()| but caches the result.
--- This means |ftplugin| and |FileType| autocommands are only --- This means |ftplugin| and |FileType| autocommands are only
--- triggered once and may not reflect later changes. --- triggered once and may not reflect later changes.
--- @since 11
--- @param filetype string Filetype --- @param filetype string Filetype
--- @param option string Option name --- @param option string Option name
--- @return string|boolean|integer: Option value --- @return string|boolean|integer: Option value

View File

@ -289,6 +289,9 @@ function Loader.load(modpath, opts)
end end
--- Finds Lua modules for the given module name. --- Finds Lua modules for the given module name.
---
--- @since 0
---
---@param modname string Module name, or `"*"` to find the top-level modules instead ---@param modname string Module name, or `"*"` to find the top-level modules instead
---@param opts? vim.loader.find.Opts Options for finding a module: ---@param opts? vim.loader.find.Opts Options for finding a module:
---@return vim.loader.ModuleInfo[] ---@return vim.loader.ModuleInfo[]
@ -377,8 +380,10 @@ function M.find(modname, opts)
return results return results
end end
--- Resets the cache for the path, or all the paths --- Resets the cache for the path, or all the paths if path is nil.
--- if path is nil. ---
--- @since 0
---
---@param path string? path to reset ---@param path string? path to reset
function M.reset(path) function M.reset(path)
if path then if path then
@ -398,6 +403,8 @@ end
--- * adds the Lua loader using the byte-compilation cache --- * adds the Lua loader using the byte-compilation cache
--- * adds the libs loader --- * adds the libs loader
--- * removes the default Nvim loader --- * removes the default Nvim loader
---
--- @since 0
function M.enable() function M.enable()
if M.enabled then if M.enabled then
return return
@ -421,6 +428,8 @@ end
--- Disables the experimental Lua module loader: --- Disables the experimental Lua module loader:
--- * removes the loaders --- * removes the loaders
--- * adds the default Nvim loader --- * adds the default Nvim loader
---
--- @since 0
function M.disable() function M.disable()
if not M.enabled then if not M.enabled then
return return

View File

@ -41,6 +41,7 @@ end
--- trusted. The user's choice is persisted in a trust database at --- trusted. The user's choice is persisted in a trust database at
--- $XDG_STATE_HOME/nvim/trust. --- $XDG_STATE_HOME/nvim/trust.
--- ---
---@since 11
---@see |:trust| ---@see |:trust|
--- ---
---@param path (string) Path to a file to read. ---@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. --- The trust database is located at |$XDG_STATE_HOME|/nvim/trust.
--- ---
---@since 11
---@param opts vim.trust.opts ---@param opts vim.trust.opts
---@return boolean success true if operation was successful ---@return boolean success true if operation was successful
---@return string msg full path if operation was successful, else error message ---@return string msg full path if operation was successful, else error message

View File

@ -447,6 +447,7 @@ end
--- ---
--- Can also be shown with `:InspectTree`. [:InspectTree]() --- Can also be shown with `:InspectTree`. [:InspectTree]()
--- ---
---@since 11
---@param opts table|nil Optional options table with the following possible keys: ---@param opts table|nil Optional options table with the following possible keys:
--- - lang (string|nil): The language of the source buffer. If omitted, detect --- - lang (string|nil): The language of the source buffer. If omitted, detect
--- from the filetype of the source buffer. --- from the filetype of the source buffer.
@ -470,6 +471,7 @@ end
--- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()' --- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
--- ``` --- ```
--- ---
---@since 11
---@param lnum integer|nil Line number to calculate fold level for ---@param lnum integer|nil Line number to calculate fold level for
---@return string ---@return string
function M.foldexpr(lnum) function M.foldexpr(lnum)

View File

@ -276,6 +276,7 @@ end
--- ``` --- ```
--- ---
--- @see # https://github.com/npm/node-semver#ranges --- @see # https://github.com/npm/node-semver#ranges
--- @since 11
--- ---
--- @param spec string Version range "spec" --- @param spec string Version range "spec"
--- @return vim.VersionRange? --- @return vim.VersionRange?
@ -375,6 +376,7 @@ end
--- ``` --- ```
--- ---
--- @note Per semver, build metadata is ignored when comparing two otherwise-equivalent versions. --- @note Per semver, build metadata is ignored when comparing two otherwise-equivalent versions.
--- @since 11
--- ---
---@param v1 vim.Version|number[]|string Version object. ---@param v1 vim.Version|number[]|string Version object.
---@param v2 vim.Version|number[]|string Version to compare with `v1`. ---@param v2 vim.Version|number[]|string Version to compare with `v1`.
@ -392,6 +394,7 @@ function M.cmp(v1, v2)
end end
---Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage. ---Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage.
---@since 11
---@param v1 vim.Version|number[]|string ---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string ---@param v2 vim.Version|number[]|string
---@return boolean ---@return boolean
@ -400,6 +403,7 @@ function M.eq(v1, v2)
end end
---Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage. ---Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage.
---@since 12
---@param v1 vim.Version|number[]|string ---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string ---@param v2 vim.Version|number[]|string
---@return boolean ---@return boolean
@ -408,6 +412,7 @@ function M.le(v1, v2)
end end
---Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage. ---Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage.
---@since 11
---@param v1 vim.Version|number[]|string ---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string ---@param v2 vim.Version|number[]|string
---@return boolean ---@return boolean
@ -416,6 +421,7 @@ function M.lt(v1, v2)
end end
---Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage. ---Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage.
---@since 12
---@param v1 vim.Version|number[]|string ---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string ---@param v2 vim.Version|number[]|string
---@return boolean ---@return boolean
@ -424,6 +430,7 @@ function M.ge(v1, v2)
end end
---Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage. ---Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage.
---@since 11
---@param v1 vim.Version|number[]|string ---@param v1 vim.Version|number[]|string
---@param v2 vim.Version|number[]|string ---@param v2 vim.Version|number[]|string
---@return boolean ---@return boolean
@ -438,7 +445,8 @@ end
--- { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } --- { 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 version string Version string to parse.
---@param opts table|nil Optional keyword arguments: ---@param opts table|nil Optional keyword arguments:

View File

@ -309,7 +309,7 @@ end
local function render_api_meta(_f, fun, write) local function render_api_meta(_f, fun, write)
write('') write('')
local text_utils = require('scripts.text_utils') local util = require('scripts.util')
if vim.startswith(fun.name, 'nvim__') then if vim.startswith(fun.name, 'nvim__') then
write('--- @private') write('--- @private')
@ -321,7 +321,7 @@ local function render_api_meta(_f, fun, write)
local desc = fun.desc local desc = fun.desc
if desc then if desc then
desc = text_utils.md_to_vimdoc(desc, 0, 0, 74) desc = util.md_to_vimdoc(desc, 0, 0, 74)
for _, l in ipairs(split(norm_text(desc))) do for _, l in ipairs(split(norm_text(desc))) do
write('--- ' .. l) write('--- ' .. l)
end end
@ -332,7 +332,7 @@ local function render_api_meta(_f, fun, write)
write('--- Note:') write('--- Note:')
for _, note in ipairs(fun.notes) do for _, note in ipairs(fun.notes) do
-- XXX: abuse md_to_vimdoc() to force-fit the markdown list. Need norm_md()? -- XXX: abuse md_to_vimdoc() to force-fit the markdown list. Need norm_md()?
note = text_utils.md_to_vimdoc(' - ' .. note, 0, 0, 74) note = util.md_to_vimdoc(' - ' .. note, 0, 0, 74)
for _, l in ipairs(split(vim.trim(norm_text(note)))) do for _, l in ipairs(split(vim.trim(norm_text(note)))) do
write('--- ' .. l:gsub('\n*$', '')) write('--- ' .. l:gsub('\n*$', ''))
end end
@ -341,7 +341,7 @@ local function render_api_meta(_f, fun, write)
end end
for _, see in ipairs(fun.see or {}) do for _, see in ipairs(fun.see or {}) do
see = text_utils.md_to_vimdoc('@see ' .. see, 0, 0, 74) see = util.md_to_vimdoc('@see ' .. see, 0, 0, 74)
for _, l in ipairs(split(vim.trim(norm_text(see)))) do for _, l in ipairs(split(vim.trim(norm_text(see)))) do
write('--- ' .. l:gsub([[\s*$]], '')) write('--- ' .. l:gsub([[\s*$]], ''))
end end
@ -355,7 +355,7 @@ local function render_api_meta(_f, fun, write)
if pdesc then if pdesc then
local s = '--- @param ' .. p[1] .. ' ' .. p[2] .. ' ' local s = '--- @param ' .. p[1] .. ' ' .. p[2] .. ' '
local indent = #('@param ' .. p[1] .. ' ') local indent = #('@param ' .. p[1] .. ' ')
pdesc = text_utils.md_to_vimdoc(pdesc, #s, indent, 74, true) pdesc = util.md_to_vimdoc(pdesc, #s, indent, 74, true)
local pdesc_a = split(vim.trim(norm_text(pdesc))) local pdesc_a = split(vim.trim(norm_text(pdesc)))
write(s .. pdesc_a[1]) write(s .. pdesc_a[1])
for i = 2, #pdesc_a do for i = 2, #pdesc_a do
@ -371,7 +371,7 @@ local function render_api_meta(_f, fun, write)
if fun.returns ~= '' then if fun.returns ~= '' then
local ret_desc = fun.returns_desc and ' : ' .. fun.returns_desc or '' local ret_desc = fun.returns_desc and ' : ' .. fun.returns_desc or ''
ret_desc = text_utils.md_to_vimdoc(ret_desc, 0, 0, 74) ret_desc = util.md_to_vimdoc(ret_desc, 0, 0, 74)
local ret = LUA_API_RETURN_OVERRIDES[fun.name] or fun.returns local ret = LUA_API_RETURN_OVERRIDES[fun.name] or fun.returns
write('--- @return ' .. ret .. ret_desc) write('--- @return ' .. ret .. ret_desc)
end end

View File

@ -18,12 +18,12 @@
local luacats_parser = require('scripts.luacats_parser') local luacats_parser = require('scripts.luacats_parser')
local cdoc_parser = require('scripts.cdoc_parser') local cdoc_parser = require('scripts.cdoc_parser')
local text_utils = require('scripts.text_utils') local util = require('scripts.util')
local fmt = string.format local fmt = string.format
local wrap = text_utils.wrap local wrap = util.wrap
local md_to_vimdoc = text_utils.md_to_vimdoc local md_to_vimdoc = util.md_to_vimdoc
local TEXT_WIDTH = 78 local TEXT_WIDTH = 78
local INDENTATION = 4 local INDENTATION = 4
@ -730,17 +730,23 @@ local function render_fun(fun, classes, cfg)
table.insert(ret, render_fun_header(fun, cfg)) table.insert(ret, render_fun_header(fun, cfg))
table.insert(ret, '\n') table.insert(ret, '\n')
if fun.desc then if fun.since then
table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH)) local since = assert(tonumber(fun.since), 'invalid @since on ' .. fun.name)
local info = nvim_api_info()
if since == 0 or (info.prerelease and since == info.level) then
-- Experimental = (since==0 or current prerelease)
local s = 'WARNING: This feature is experimental/unstable.'
table.insert(ret, md_to_vimdoc(s, INDENTATION, INDENTATION, TEXT_WIDTH))
table.insert(ret, '\n')
else
local v = assert(util.version_level[since], 'invalid @since on ' .. fun.name)
fun.attrs = fun.attrs or {}
table.insert(fun.attrs, ('Since: %s'):format(v))
end
end end
if fun.since then if fun.desc then
local since = tonumber(fun.since) table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
local info = nvim_api_info()
if since and (since > info.level or since == info.level and info.prerelease) then
fun.notes = fun.notes or {}
table.insert(fun.notes, { desc = 'This API is pre-release (unstable).' })
end
end end
if fun.notes then if fun.notes then

View File

@ -1,7 +1,9 @@
-- TODO(justinmk): move most of this to `vim.text`.
local fmt = string.format local fmt = string.format
--- @class nvim.text_utils.MDNode --- @class nvim.util.MDNode
--- @field [integer] nvim.text_utils.MDNode --- @field [integer] nvim.util.MDNode
--- @field type string --- @field type string
--- @field text? string --- @field text? string
@ -15,6 +17,23 @@ local function contains(t, xs)
return vim.tbl_contains(xs, t) return vim.tbl_contains(xs, t)
end end
-- Map of api_level:version, by inspection of:
-- :lua= vim.mpack.decode(vim.fn.readfile('test/functional/fixtures/api_level_9.mpack','B')).version
M.version_level = {
[12] = '0.10.0',
[11] = '0.9.0',
[10] = '0.8.0',
[9] = '0.7.0',
[8] = '0.6.0',
[7] = '0.5.0',
[6] = '0.4.0',
[5] = '0.3.2',
[4] = '0.3.0',
[3] = '0.2.1',
[2] = '0.2.0',
[1] = '0.1.0',
}
--- @param txt string --- @param txt string
--- @param srow integer --- @param srow integer
--- @param scol integer --- @param scol integer
@ -47,13 +66,13 @@ local function slice_text(txt, srow, scol, erow, ecol)
end end
--- @param text string --- @param text string
--- @return nvim.text_utils.MDNode --- @return nvim.util.MDNode
local function parse_md_inline(text) local function parse_md_inline(text)
local parser = vim.treesitter.languagetree.new(text, 'markdown_inline') local parser = vim.treesitter.languagetree.new(text, 'markdown_inline')
local root = parser:parse(true)[1]:root() local root = parser:parse(true)[1]:root()
--- @param node TSNode --- @param node TSNode
--- @return nvim.text_utils.MDNode? --- @return nvim.util.MDNode?
local function extract(node) local function extract(node)
local ntype = node:type() local ntype = node:type()
@ -101,7 +120,7 @@ local function parse_md_inline(text)
end end
--- @param text string --- @param text string
--- @return nvim.text_utils.MDNode --- @return nvim.util.MDNode
local function parse_md(text) local function parse_md(text)
local parser = vim.treesitter.languagetree.new(text, 'markdown', { local parser = vim.treesitter.languagetree.new(text, 'markdown', {
injections = { markdown = '' }, injections = { markdown = '' },
@ -119,7 +138,7 @@ local function parse_md(text)
} }
--- @param node TSNode --- @param node TSNode
--- @return nvim.text_utils.MDNode? --- @return nvim.util.MDNode?
local function extract(node) local function extract(node)
local ntype = node:type() local ntype = node:type()
@ -179,7 +198,7 @@ function M.wrap(x, start_indent, indent, text_width)
return (table.concat(parts):gsub('%s+\n', '\n'):gsub('\n+$', '')) return (table.concat(parts):gsub('%s+\n', '\n'):gsub('\n+$', ''))
end end
--- @param node nvim.text_utils.MDNode --- @param node nvim.util.MDNode
--- @param start_indent integer --- @param start_indent integer
--- @param indent integer --- @param indent integer
--- @param text_width integer --- @param text_width integer

View File

@ -11,8 +11,8 @@ local function md_to_vimdoc(text, start_indent, indent, text_width)
start_indent = start_indent or 0 start_indent = start_indent or 0
indent = indent or 0 indent = indent or 0
text_width = text_width or 70 text_width = text_width or 70
local text_utils = require('scripts/text_utils') local util = require('scripts/util')
return text_utils.md_to_vimdoc(table.concat(text, '\n'), start_indent, indent, text_width) return util.md_to_vimdoc(table.concat(text, '\n'), start_indent, indent, text_width)
]], ]],
text, text,
start_indent, start_indent,