From b45c50f3140e7ece593f2126840900f5cc3d39ea Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Fri, 4 Oct 2024 02:13:31 -0700
Subject: [PATCH] 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
---
 runtime/doc/develop.txt                    |  7 ++-
 runtime/doc/diagnostic.txt                 |  3 ++
 runtime/doc/lsp.txt                        |  9 ++++
 runtime/doc/lua.txt                        | 51 +++++++++++++++++++++-
 runtime/doc/treesitter.txt                 |  6 +++
 runtime/lua/vim/_inspector.lua             |  2 +
 runtime/lua/vim/_meta/builtin.lua          |  4 +-
 runtime/lua/vim/filetype.lua               |  1 +
 runtime/lua/vim/loader.lua                 | 13 +++++-
 runtime/lua/vim/secure.lua                 |  2 +
 runtime/lua/vim/treesitter.lua             |  2 +
 runtime/lua/vim/version.lua                | 10 ++++-
 scripts/gen_eval_files.lua                 | 12 ++---
 scripts/gen_vimdoc.lua                     | 30 ++++++++-----
 scripts/{text_utils.lua => util.lua}       | 33 +++++++++++---
 test/functional/script/text_utils_spec.lua |  4 +-
 16 files changed, 156 insertions(+), 33 deletions(-)
 rename scripts/{text_utils.lua => util.lua} (93%)

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:
diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 6c97893a4a..234028b972 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -309,7 +309,7 @@ end
 local function render_api_meta(_f, fun, write)
   write('')
 
-  local text_utils = require('scripts.text_utils')
+  local util = require('scripts.util')
 
   if vim.startswith(fun.name, 'nvim__') then
     write('--- @private')
@@ -321,7 +321,7 @@ local function render_api_meta(_f, fun, write)
 
   local desc = fun.desc
   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
       write('--- ' .. l)
     end
@@ -332,7 +332,7 @@ local function render_api_meta(_f, fun, write)
     write('--- Note:')
     for _, note in ipairs(fun.notes) do
       -- 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
         write('--- ' .. l:gsub('\n*$', ''))
       end
@@ -341,7 +341,7 @@ local function render_api_meta(_f, fun, write)
   end
 
   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
       write('--- ' .. l:gsub([[\s*$]], ''))
     end
@@ -355,7 +355,7 @@ local function render_api_meta(_f, fun, write)
     if pdesc then
       local s = '--- @param ' .. p[1] .. ' ' .. p[2] .. ' '
       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)))
       write(s .. pdesc_a[1])
       for i = 2, #pdesc_a do
@@ -371,7 +371,7 @@ local function render_api_meta(_f, fun, write)
 
   if fun.returns ~= '' then
     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
     write('--- @return ' .. ret .. ret_desc)
   end
diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua
index 66b72e0c40..8908097397 100755
--- a/scripts/gen_vimdoc.lua
+++ b/scripts/gen_vimdoc.lua
@@ -18,12 +18,12 @@
 
 local luacats_parser = require('scripts.luacats_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 wrap = text_utils.wrap
-local md_to_vimdoc = text_utils.md_to_vimdoc
+local wrap = util.wrap
+local md_to_vimdoc = util.md_to_vimdoc
 
 local TEXT_WIDTH = 78
 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, '\n')
 
-  if fun.desc then
-    table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
+  if fun.since then
+    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
 
-  if fun.since then
-    local since = tonumber(fun.since)
-    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
+  if fun.desc then
+    table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
   end
 
   if fun.notes then
diff --git a/scripts/text_utils.lua b/scripts/util.lua
similarity index 93%
rename from scripts/text_utils.lua
rename to scripts/util.lua
index 3569f5a5af..94598c32a6 100644
--- a/scripts/text_utils.lua
+++ b/scripts/util.lua
@@ -1,7 +1,9 @@
+-- TODO(justinmk): move most of this to `vim.text`.
+
 local fmt = string.format
 
---- @class nvim.text_utils.MDNode
---- @field [integer] nvim.text_utils.MDNode
+--- @class nvim.util.MDNode
+--- @field [integer] nvim.util.MDNode
 --- @field type string
 --- @field text? string
 
@@ -15,6 +17,23 @@ local function contains(t, xs)
   return vim.tbl_contains(xs, t)
 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 srow integer
 --- @param scol integer
@@ -47,13 +66,13 @@ local function slice_text(txt, srow, scol, erow, ecol)
 end
 
 --- @param text string
---- @return nvim.text_utils.MDNode
+--- @return nvim.util.MDNode
 local function parse_md_inline(text)
   local parser = vim.treesitter.languagetree.new(text, 'markdown_inline')
   local root = parser:parse(true)[1]:root()
 
   --- @param node TSNode
-  --- @return nvim.text_utils.MDNode?
+  --- @return nvim.util.MDNode?
   local function extract(node)
     local ntype = node:type()
 
@@ -101,7 +120,7 @@ local function parse_md_inline(text)
 end
 
 --- @param text string
---- @return nvim.text_utils.MDNode
+--- @return nvim.util.MDNode
 local function parse_md(text)
   local parser = vim.treesitter.languagetree.new(text, 'markdown', {
     injections = { markdown = '' },
@@ -119,7 +138,7 @@ local function parse_md(text)
   }
 
   --- @param node TSNode
-  --- @return nvim.text_utils.MDNode?
+  --- @return nvim.util.MDNode?
   local function extract(node)
     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+$', ''))
 end
 
---- @param node nvim.text_utils.MDNode
+--- @param node nvim.util.MDNode
 --- @param start_indent integer
 --- @param indent integer
 --- @param text_width integer
diff --git a/test/functional/script/text_utils_spec.lua b/test/functional/script/text_utils_spec.lua
index 176c2ef816..74098b9287 100644
--- a/test/functional/script/text_utils_spec.lua
+++ b/test/functional/script/text_utils_spec.lua
@@ -11,8 +11,8 @@ local function md_to_vimdoc(text, start_indent, indent, text_width)
     start_indent = start_indent or 0
     indent = indent or 0
     text_width = text_width or 70
-    local text_utils = require('scripts/text_utils')
-    return text_utils.md_to_vimdoc(table.concat(text, '\n'), start_indent, indent, text_width)
+    local util = require('scripts/util')
+    return util.md_to_vimdoc(table.concat(text, '\n'), start_indent, indent, text_width)
   ]],
     text,
     start_indent,