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

7 files changed, 30 insertions, 4 deletions

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: