From 8cbb1f20e557461c8417583a7f69d53aaaef920b Mon Sep 17 00:00:00 2001
From: Ilia Choly <ilia.choly@gmail.com>
Date: Tue, 4 Jun 2024 09:06:02 -0400
Subject: refactor(lua): use tuple syntax everywhere #29111

---
 scripts/gen_eval_files.lua | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index f1bba5c0a2..76092f8b39 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -6,7 +6,7 @@ local DEP_API_METADATA = 'build/funcs_metadata.mpack'
 
 --- @class vim.api.metadata
 --- @field name string
---- @field parameters {[1]:string,[2]:string}[]
+--- @field parameters [string,string][]
 --- @field return_type string
 --- @field deprecated_since integer
 --- @field eval boolean
@@ -149,7 +149,7 @@ local function api_type(t)
 end
 
 --- @param f string
---- @param params {[1]:string,[2]:string}[]|true
+--- @param params [string,string][]|true
 --- @return string
 local function render_fun_sig(f, params)
   local param_str --- @type string
@@ -158,7 +158,7 @@ local function render_fun_sig(f, params)
   else
     param_str = table.concat(
       vim.tbl_map(
-        --- @param v {[1]:string,[2]:string}
+        --- @param v [string,string]
         --- @return string
         function(v)
           return v[1]
@@ -178,8 +178,8 @@ end
 
 --- Uniquify names
 --- Fix any names that are lua keywords
---- @param params {[1]:string,[2]:string,[3]:string}[]
---- @return {[1]:string,[2]:string,[3]:string}[]
+--- @param params [string,string,string][]
+--- @return [string,string,string][]
 local function process_params(params)
   local seen = {} --- @type table<string,true>
   local sfx = 1
@@ -245,7 +245,7 @@ local function get_api_meta()
   for _, fun in pairs(functions) do
     local deprecated = fun.deprecated_since ~= nil
 
-    local params = {} --- @type {[1]:string,[2]:string}[]
+    local params = {} --- @type [string,string][]
     for _, p in ipairs(fun.params) do
       params[#params + 1] = {
         p.name,
-- 
cgit 


From 545aafbeb80eb52c182ce139800489b392a12d0d Mon Sep 17 00:00:00 2001
From: zeertzjq <zeertzjq@outlook.com>
Date: Wed, 10 Jul 2024 08:07:16 +0800
Subject: vim-patch:9.1.0547: No way to get the arity of a Vim function
 (#29638)

Problem:  No way to get the arity of a Vim function
          (Austin Ziegler)
Solution: Enhance get() Vim script function to return the function
          argument info using get(func, "arity") (LemonBoy)

fixes: vim/vim#15097
closes: vim/vim#15109

https://github.com/vim/vim/commit/48b7d05a4f88c4326bd5d7a73a523f2d953b3e51

Co-authored-by: LemonBoy <thatlemon@gmail.com>
---
 scripts/gen_eval_files.lua | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 76092f8b39..b490e7b480 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -432,14 +432,15 @@ local function render_eval_meta(f, fun, write)
 end
 
 --- @param name string
+--- @param name_tag boolean
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
-local function render_sig_and_tag(name, fun, write)
+local function render_sig_and_tag(name, name_tag, fun, write)
   if not fun.signature then
     return
   end
 
-  local tags = { '*' .. name .. '()*' }
+  local tags = name_tag and { '*' .. name .. '()*' } or {}
 
   if fun.tags then
     for _, t in ipairs(fun.tags) do
@@ -447,6 +448,11 @@ local function render_sig_and_tag(name, fun, write)
     end
   end
 
+  if #tags == 0 then
+    write(fun.signature)
+    return
+  end
+
   local tag = table.concat(tags, ' ')
   local siglen = #fun.signature
   local conceal_offset = 2 * (#tags - 1)
@@ -472,11 +478,7 @@ local function render_eval_doc(f, fun, write)
     return
   end
 
-  if f:find('__%d+$') then
-    write(fun.signature)
-  else
-    render_sig_and_tag(fun.name or f, fun, write)
-  end
+  render_sig_and_tag(fun.name or f, not f:find('__%d+$'), fun, write)
 
   if not fun.desc then
     return
-- 
cgit 


From f926cc32c9262b6254e2843276b951cef9da1afe Mon Sep 17 00:00:00 2001
From: bfredl <bjorn.linse@gmail.com>
Date: Tue, 2 Jul 2024 13:45:50 +0200
Subject: refactor(shada): rework msgpack decoding without msgpack-c

This also makes shada reading slightly faster due to avoiding
some copying and allocation.

Use keysets to drive decoding of msgpack maps for shada entries.
---
 scripts/gen_eval_files.lua | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index b490e7b480..fc2fadc440 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -376,6 +376,9 @@ end
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
 local function render_api_keyset_meta(_f, fun, write)
+  if string.sub(fun.name, 1, 1) == '_' then
+    return -- not exported
+  end
   write('')
   write('--- @class vim.api.keyset.' .. fun.name)
   for _, p in ipairs(fun.params) do
-- 
cgit 


From a901fb875f69ff4e3033f883d5b8665eb608a586 Mon Sep 17 00:00:00 2001
From: Maria José Solano <majosolano99@gmail.com>
Date: Fri, 16 Aug 2024 08:36:23 -0700
Subject: fix(docs): add missing properties to hl_info #30032

---
 scripts/gen_eval_files.lua | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index fc2fadc440..a5f9449049 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -29,11 +29,11 @@ local LUA_API_RETURN_OVERRIDES = {
   nvim_get_keymap = 'vim.api.keyset.keymap[]',
   nvim_get_mark = 'vim.api.keyset.get_mark',
 
-  -- Can also return table<string,vim.api.keyset.hl_info>, however we need to
+  -- Can also return table<string,vim.api.keyset.get_hl_info>, however we need to
   -- pick one to get some benefit.
   -- REVISIT lewrus01 (26/01/24): we can maybe add
-  -- @overload fun(ns: integer, {}): table<string,vim.api.keyset.hl_info>
-  nvim_get_hl = 'vim.api.keyset.hl_info',
+  -- @overload fun(ns: integer, {}): table<string,vim.api.keyset.get_hl_info>
+  nvim_get_hl = 'vim.api.keyset.get_hl_info',
 
   nvim_get_mode = 'vim.api.keyset.get_mode',
   nvim_get_namespaces = 'table<string,integer>',
-- 
cgit 


From b8135a76b71f1af0d708e3dc58ccb58abad59f7c Mon Sep 17 00:00:00 2001
From: JonnyKong <jonnykong1996@gmail.com>
Date: Sun, 25 Aug 2024 03:57:02 +0000
Subject: fix(docs): wrong return value annotation for `nvim_buf_get_extmarks`

---
 scripts/gen_eval_files.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index a5f9449049..93621551ea 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -20,7 +20,7 @@ local DEP_API_METADATA = 'build/funcs_metadata.mpack'
 
 local LUA_API_RETURN_OVERRIDES = {
   nvim_buf_get_command = 'table<string,vim.api.keyset.command_info>',
-  nvim_buf_get_extmark_by_id = 'vim.api.keyset.get_extmark_item',
+  nvim_buf_get_extmark_by_id = 'vim.api.keyset.get_extmark_item_by_id',
   nvim_buf_get_extmarks = 'vim.api.keyset.get_extmark_item[]',
   nvim_buf_get_keymap = 'vim.api.keyset.keymap[]',
   nvim_get_autocmds = 'vim.api.keyset.get_autocmds.ret[]',
-- 
cgit 


From 737f58e23230ea14f1648ac1fc7f442ea0f8563c Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Fri, 20 Sep 2024 07:34:50 +0200
Subject: refactor(api)!: rename Dictionary => Dict

In the api_info() output:

    :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val')
    ...

    {'return_type': 'ArrayOf(Integer, 2)', 'name': 'nvim_win_get_position', 'method': v:true, 'parameters': [['Window', 'window']], 'since': 1}

The `ArrayOf(Integer, 2)` return type didn't break clients when we added
it, which is evidence that clients don't use the `return_type` field,
thus renaming Dictionary => Dict in api_info() is not (in practice)
a breaking change.
---
 scripts/gen_eval_files.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 93621551ea..35af84ae28 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -112,7 +112,7 @@ local API_TYPES = {
   String = 'string',
   Array = 'any[]',
   LuaRef = 'function',
-  Dictionary = 'table<string,any>',
+  Dict = 'table<string,any>',
   Float = 'number',
   HLGroupID = 'number|string',
   void = '',
@@ -140,7 +140,7 @@ local function api_type(t)
     return 'vim.api.keyset.' .. d
   end
 
-  local d0 = t:match('^DictionaryOf%((.*)%)')
+  local d0 = t:match('^DictOf%((.*)%)')
   if d0 then
     return 'table<string,' .. api_type(d0) .. '>'
   end
-- 
cgit 


From ce7017b850e0f62b3ebe6ea0d7010ba0291624e5 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Wed, 25 Sep 2024 02:34:13 -0700
Subject: docs: render @see, @note items in _meta/api.lua #30494

---
 scripts/gen_eval_files.lua | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 35af84ae28..6c97893a4a 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -245,6 +245,16 @@ local function get_api_meta()
   for _, fun in pairs(functions) do
     local deprecated = fun.deprecated_since ~= nil
 
+    local notes = {} --- @type string[]
+    for _, note in ipairs(fun.notes or {}) do
+      notes[#notes + 1] = note.desc
+    end
+
+    local sees = {} --- @type string[]
+    for _, see in ipairs(fun.see or {}) do
+      sees[#sees + 1] = see.desc
+    end
+
     local params = {} --- @type [string,string][]
     for _, p in ipairs(fun.params) do
       params[#params + 1] = {
@@ -258,6 +268,8 @@ local function get_api_meta()
       signature = 'NA',
       name = fun.name,
       params = params,
+      notes = notes,
+      see = sees,
       returns = api_type(fun.returns[1].type),
       deprecated = deprecated,
     }
@@ -315,6 +327,26 @@ local function render_api_meta(_f, fun, write)
     end
   end
 
+  -- LuaLS doesn't support @note. Render @note items as a markdown list.
+  if fun.notes and #fun.notes > 0 then
+    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)
+      for _, l in ipairs(split(vim.trim(norm_text(note)))) do
+        write('--- ' .. l:gsub('\n*$', ''))
+      end
+    end
+    write('---')
+  end
+
+  for _, see in ipairs(fun.see or {}) do
+    see = text_utils.md_to_vimdoc('@see ' .. see, 0, 0, 74)
+    for _, l in ipairs(split(vim.trim(norm_text(see)))) do
+      write('--- ' .. l:gsub([[\s*$]], ''))
+    end
+  end
+
   local param_names = {} --- @type string[]
   local params = process_params(fun.params)
   for _, p in ipairs(params) do
@@ -336,6 +368,7 @@ local function render_api_meta(_f, fun, write)
       write('--- @param ' .. p[1] .. ' ' .. p[2])
     end
   end
+
   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)
-- 
cgit 


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: 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
---
 scripts/gen_eval_files.lua | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

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
-- 
cgit 


From 8801b77ed09876605e42f4a3fddf8c020c14b711 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Sat, 5 Oct 2024 08:52:57 -0700
Subject: fix(docs): missing `@returns` desc in _meta/api.lua #30673

---
 scripts/gen_eval_files.lua | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 234028b972..095daaeb21 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -276,7 +276,7 @@ local function get_api_meta()
 
     if not deprecated then
       r.desc = fun.desc
-      r.return_desc = fun.returns[1].desc
+      r.returns_desc = fun.returns[1].desc
     end
 
     ret[fun.name] = r
@@ -370,10 +370,9 @@ local function render_api_meta(_f, fun, write)
   end
 
   if fun.returns ~= '' then
-    local ret_desc = fun.returns_desc and ' : ' .. fun.returns_desc or ''
-    ret_desc = util.md_to_vimdoc(ret_desc, 0, 0, 74)
+    local ret_desc = fun.returns_desc and ' # ' .. fun.returns_desc or ''
     local ret = LUA_API_RETURN_OVERRIDES[fun.name] or fun.returns
-    write('--- @return ' .. ret .. ret_desc)
+    write(util.prefix('--- ', '@return ' .. ret .. ret_desc))
   end
   local param_str = table.concat(param_names, ', ')
 
-- 
cgit 


From 056009f74146b349c66790fbcba3130e85a6c6da Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Sun, 6 Oct 2024 03:24:21 -0700
Subject: fix(docs): markdown instead of vimdoc in meta docstrings #30680

LuaLS/meta docstrings expect markdown, not vimdoc. This matters for lists, codeblocks, etc.

Also, line length doesn't matter for docstrings.
---
 scripts/gen_eval_files.lua | 22 ++++------------------
 1 file changed, 4 insertions(+), 18 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 095daaeb21..6aa8ee0112 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -321,30 +321,18 @@ local function render_api_meta(_f, fun, write)
 
   local desc = fun.desc
   if desc then
-    desc = util.md_to_vimdoc(desc, 0, 0, 74)
-    for _, l in ipairs(split(norm_text(desc))) do
-      write('--- ' .. l)
-    end
+    write(util.prefix_lines('--- ', norm_text(desc)))
   end
 
   -- LuaLS doesn't support @note. Render @note items as a markdown list.
   if fun.notes and #fun.notes > 0 then
     write('--- Note:')
-    for _, note in ipairs(fun.notes) do
-      -- XXX: abuse md_to_vimdoc() to force-fit the markdown list. Need norm_md()?
-      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
-    end
+    write(util.prefix_lines('--- ', table.concat(fun.notes, '\n')))
     write('---')
   end
 
   for _, see in ipairs(fun.see or {}) do
-    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
+    write(util.prefix_lines('--- @see ', norm_text(see)))
   end
 
   local param_names = {} --- @type string[]
@@ -354,8 +342,6 @@ local function render_api_meta(_f, fun, write)
     local pdesc = p[3]
     if pdesc then
       local s = '--- @param ' .. p[1] .. ' ' .. p[2] .. ' '
-      local indent = #('@param ' .. p[1] .. ' ')
-      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
@@ -372,7 +358,7 @@ local function render_api_meta(_f, fun, write)
   if fun.returns ~= '' then
     local ret_desc = fun.returns_desc and ' # ' .. fun.returns_desc or ''
     local ret = LUA_API_RETURN_OVERRIDES[fun.name] or fun.returns
-    write(util.prefix('--- ', '@return ' .. ret .. ret_desc))
+    write(util.prefix_lines('--- ', '@return ' .. ret .. ret_desc))
   end
   local param_str = table.concat(param_names, ', ')
 
-- 
cgit 


From 6628741ada73bcf60dd1cb249178aa18e60dbebc Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Sun, 6 Oct 2024 09:12:35 -0700
Subject: feat(docs): improve `@see` meta docstrings #30693

---
 scripts/gen_eval_files.lua | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 6aa8ee0112..25f3e30b74 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -199,14 +199,6 @@ local function process_params(params)
   return params
 end
 
---- @class vim.gen_vim_doc_fun
---- @field signature string
---- @field doc string[]
---- @field parameters_doc table<string,string>
---- @field return string[]
---- @field seealso string[]
---- @field annotations string[]
-
 --- @return table<string, vim.EvalFn>
 local function get_api_meta()
   local ret = {} --- @type table<string, vim.EvalFn>
@@ -290,8 +282,19 @@ end
 --- Ensure code blocks have one empty line before the start fence and after the closing fence.
 ---
 --- @param x string
+--- @param special string?
+---                | 'see-api-meta' Normalize `@see` for API meta docstrings.
 --- @return string
-local function norm_text(x)
+local function norm_text(x, special)
+  if special == 'see-api-meta' then
+    -- Try to guess a symbol that actually works in @see.
+    -- "nvim_xx()" => "vim.api.nvim_xx"
+    x = x:gsub([=[%|?(nvim_[^.()| ]+)%(?%)?%|?]=], 'vim.api.%1')
+    -- TODO: Remove backticks when LuaLS resolves: https://github.com/LuaLS/lua-language-server/issues/2889
+    -- "|foo|" => "`:help foo`"
+    x = x:gsub([=[|([^ ]+)|]=], '`:help %1`')
+  end
+
   return (
     x:gsub('|([^ ]+)|', '`%1`')
       :gsub('\n*>lua', '\n\n```lua')
@@ -332,7 +335,7 @@ local function render_api_meta(_f, fun, write)
   end
 
   for _, see in ipairs(fun.see or {}) do
-    write(util.prefix_lines('--- @see ', norm_text(see)))
+    write(util.prefix_lines('--- @see ', norm_text(see, 'see-api-meta')))
   end
 
   local param_names = {} --- @type string[]
-- 
cgit 


From 7335988ce6a5f41a8405462c6c4c90a54d3e588c Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Mon, 7 Oct 2024 05:32:49 -0700
Subject: docs: generate params/returns in builtin.txt #30654

---
 scripts/gen_eval_files.lua | 64 ++++++++++++++++++++++++++++++++--------------
 1 file changed, 45 insertions(+), 19 deletions(-)

(limited to 'scripts/gen_eval_files.lua')

diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 25f3e30b74..b9ea4e73f0 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -2,7 +2,11 @@
 
 -- Generator for various vimdoc and Lua type files
 
+local util = require('scripts.util')
+local fmt = string.format
+
 local DEP_API_METADATA = 'build/funcs_metadata.mpack'
+local TEXT_WIDTH = 78
 
 --- @class vim.api.metadata
 --- @field name string
@@ -170,9 +174,9 @@ local function render_fun_sig(f, params)
   end
 
   if LUA_KEYWORDS[f] then
-    return string.format("vim.fn['%s'] = function(%s) end", f, param_str)
+    return fmt("vim.fn['%s'] = function(%s) end", f, param_str)
   else
-    return string.format('function vim.fn.%s(%s) end', f, param_str)
+    return fmt('function vim.fn.%s(%s) end', f, param_str)
   end
 end
 
@@ -306,14 +310,13 @@ local function norm_text(x, special)
   )
 end
 
+--- Generates LuaLS docstring for an API function.
 --- @param _f string
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
 local function render_api_meta(_f, fun, write)
   write('')
 
-  local util = require('scripts.util')
-
   if vim.startswith(fun.name, 'nvim__') then
     write('--- @private')
   end
@@ -365,7 +368,7 @@ local function render_api_meta(_f, fun, write)
   end
   local param_str = table.concat(param_names, ', ')
 
-  write(string.format('function vim.api.%s(%s) end', fun.name, param_str))
+  write(fmt('function vim.api.%s(%s) end', fun.name, param_str))
 end
 
 --- @return table<string, vim.EvalFn>
@@ -393,6 +396,7 @@ local function get_api_keysets_meta()
   return ret
 end
 
+--- Generates LuaLS docstring for an API keyset.
 --- @param _f string
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
@@ -412,6 +416,7 @@ local function get_eval_meta()
   return require('src/nvim/eval').funcs
 end
 
+--- Generates LuaLS docstring for a Vimscript "eval" function.
 --- @param f string
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
@@ -421,7 +426,6 @@ local function render_eval_meta(f, fun, write)
   end
 
   local funname = fun.name or f
-
   local params = process_params(fun.params)
 
   write('')
@@ -445,16 +449,18 @@ local function render_eval_meta(f, fun, write)
   for i, param in ipairs(params) do
     local pname, ptype = param[1], param[2]
     local optional = (pname ~= '...' and i > req_args) and '?' or ''
-    write(string.format('--- @param %s%s %s', pname, optional, ptype))
+    write(fmt('--- @param %s%s %s', pname, optional, ptype))
   end
 
   if fun.returns ~= false then
-    write('--- @return ' .. (fun.returns or 'any'))
+    local ret_desc = fun.returns_desc and ' # ' .. fun.returns_desc or ''
+    write('--- @return ' .. (fun.returns or 'any') .. ret_desc)
   end
 
   write(render_fun_sig(funname, params))
 end
 
+--- Generates vimdoc heading for a Vimscript "eval" function signature.
 --- @param name string
 --- @param name_tag boolean
 --- @param fun vim.EvalFn
@@ -486,19 +492,16 @@ local function render_sig_and_tag(name, name_tag, fun, write)
     write(string.rep(' ', tag_pad_len) .. tag)
     write(fun.signature)
   else
-    write(string.format('%s%s%s', fun.signature, string.rep(' ', tag_pad_len - siglen), tag))
+    write(fmt('%s%s%s', fun.signature, string.rep(' ', tag_pad_len - siglen), tag))
   end
 end
 
+--- Generates vimdoc for a Vimscript "eval" function.
 --- @param f string
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
 local function render_eval_doc(f, fun, write)
-  if fun.deprecated then
-    return
-  end
-
-  if not fun.signature then
+  if fun.deprecated or not fun.signature then
     return
   end
 
@@ -508,6 +511,9 @@ local function render_eval_doc(f, fun, write)
     return
   end
 
+  local params = process_params(fun.params)
+  local req_args = type(fun.args) == 'table' and fun.args[1] or fun.args or 0
+
   local desc_l = split(vim.trim(fun.desc))
   for _, l in ipairs(desc_l) do
     l = l:gsub('^      ', '')
@@ -523,6 +529,26 @@ local function render_eval_doc(f, fun, write)
   if #desc_l > 0 and not desc_l[#desc_l]:match('^<?$') then
     write('')
   end
+
+  if #params > 0 then
+    write(util.md_to_vimdoc('Parameters: ~', 16, 16, TEXT_WIDTH))
+    for i, param in ipairs(params) do
+      local pname, ptype = param[1], param[2]
+      local optional = (pname ~= '...' and i > req_args) and '?' or ''
+      local s = fmt('- %-14s (`%s%s`)', fmt('{%s}', pname), ptype, optional)
+      write(util.md_to_vimdoc(s, 16, 18, TEXT_WIDTH))
+    end
+    write('')
+  end
+
+  if fun.returns ~= false then
+    write(util.md_to_vimdoc('Return: ~', 16, 16, TEXT_WIDTH))
+    local ret = ('(`%s`)'):format((fun.returns or 'any'))
+    ret = ret .. (fun.returns_desc and ' ' .. fun.returns_desc or '')
+    ret = util.md_to_vimdoc(ret, 18, 18, TEXT_WIDTH)
+    write(ret)
+    write('')
+  end
 end
 
 --- @param d vim.option_defaults
@@ -760,9 +786,9 @@ local function render_option_doc(_f, opt, write)
 
   local name_str --- @type string
   if opt.abbreviation then
-    name_str = string.format("'%s' '%s'", opt.full_name, opt.abbreviation)
+    name_str = fmt("'%s' '%s'", opt.full_name, opt.abbreviation)
   else
-    name_str = string.format("'%s'", opt.full_name)
+    name_str = fmt("'%s'", opt.full_name)
   end
 
   local otype = opt.type == 'boolean' and 'boolean' or opt.type
@@ -770,13 +796,13 @@ local function render_option_doc(_f, opt, write)
     local v = render_option_default(opt.defaults, true)
     local pad = string.rep('\t', math.max(1, math.ceil((24 - #name_str) / 8)))
     if opt.defaults.doc then
-      local deflen = #string.format('%s%s%s (', name_str, pad, otype)
+      local deflen = #fmt('%s%s%s (', name_str, pad, otype)
       --- @type string
       v = v:gsub('\n', '\n' .. string.rep(' ', deflen - 2))
     end
-    write(string.format('%s%s%s\t(default %s)', name_str, pad, otype, v))
+    write(fmt('%s%s%s\t(default %s)', name_str, pad, otype, v))
   else
-    write(string.format('%s\t%s', name_str, otype))
+    write(fmt('%s\t%s', name_str, otype))
   end
 
   write('\t\t\t' .. scope_to_doc(opt.scope) .. scope_more_doc(opt))
-- 
cgit