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

3 files changed, 49 insertions, 24 deletions

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,19 +730,25 @@ 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))
-  end
-
   if fun.since then
-    local since = tonumber(fun.since)
+    local since = assert(tonumber(fun.since), 'invalid @since on ' .. fun.name)
     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).' })
+    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.desc then
+    table.insert(ret, md_to_vimdoc(fun.desc, INDENTATION, INDENTATION, TEXT_WIDTH))
+  end
+
   if fun.notes then
     table.insert(ret, '\n    Note: ~\n')
     for _, p in ipairs(fun.notes) do
diff --git a/scripts/text_utils.lua b/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