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

1 files changed, 9 insertions, 1 deletions

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: