Merge remote-tracking branch 'upstream/master' into userreg

19 files changed, 3429 insertions, 2404 deletions

diff --git a/scripts/bump_deps.lua b/scripts/bump_deps.lua
index 076ad374cf..c5294893e0 100755
--- a/scripts/bump_deps.lua
+++ b/scripts/bump_deps.lua
@@ -138,9 +138,10 @@ local function get_archive_info(repo, ref)
     'Failed to download archive from GitHub'
   )
 
-  local shacmd = (vim.fn.executable('sha256sum') == 1
-    and{ 'sha256sum', archive_path }
-    or { 'shasum', '-a', '256', archive_path })
+  local shacmd = (
+    vim.fn.executable('sha256sum') == 1 and { 'sha256sum', archive_path }
+    or { 'shasum', '-a', '256', archive_path }
+  )
   local archive_sha = run(shacmd):gmatch('%w+')()
   return { url = archive_url, sha = archive_sha }
 end
@@ -152,18 +153,7 @@ local function write_cmakelists_line(symbol, kind, value)
     'sed',
     '-i',
     '-e',
-    's/'
-      .. symbol
-      .. '_'
-      .. kind
-      .. '.*$'
-      .. '/'
-      .. symbol
-      .. '_'
-      .. kind
-      .. ' '
-      .. value
-      .. '/',
+    's/' .. symbol .. '_' .. kind .. '.*$' .. '/' .. symbol .. '_' .. kind .. ' ' .. value .. '/',
     deps_file,
   }, 'Failed to write ' .. deps_file)
 end
@@ -203,16 +193,13 @@ local function update_cmakelists(dependency, archive, comment)
   p('Updating ' .. dependency.name .. ' to ' .. archive.url .. '\n')
   write_cmakelists_line(dependency.symbol, 'URL', archive.url:gsub('/', '\\/'))
   write_cmakelists_line(dependency.symbol, 'SHA256', archive.sha)
-  run_die(
-    {
-      'git',
-      'commit',
-      deps_file,
-      '-m',
-      commit_prefix .. 'bump ' .. dependency.name .. ' to ' .. comment,
-    },
-    'git failed to commit'
-  )
+  run_die({
+    'git',
+    'commit',
+    deps_file,
+    '-m',
+    commit_prefix .. 'bump ' .. dependency.name .. ' to ' .. comment,
+  }, 'git failed to commit')
 end
 
 local function verify_cmakelists_committed()
@@ -318,9 +305,9 @@ function M.commit(dependency_name, commit)
 end
 
 function M.version(dependency_name, version)
-  vim.validate{
-    dependency_name={dependency_name,'s'},
-    version={version,'s'},
+  vim.validate {
+    dependency_name = { dependency_name, 's' },
+    version = { version, 's' },
   }
   local dependency = assert(get_dependency(dependency_name))
   verify_cmakelists_committed()
@@ -384,7 +371,7 @@ function M.submit_pr()
 end
 
 local function usage()
-  local this_script = _G.arg[0]:match("[^/]*.lua$")
+  local this_script = _G.arg[0]:match('[^/]*.lua$')
   print(([=[
     Bump Nvim dependencies
 
@@ -421,13 +408,13 @@ local function parseargs()
     elseif _G.arg[i] == '--pr' then
       args.pr = true
     elseif _G.arg[i] == '--branch' then
-      args.branch = _G.arg[i+1]
+      args.branch = _G.arg[i + 1]
     elseif _G.arg[i] == '--dep' then
-      args.dep = _G.arg[i+1]
+      args.dep = _G.arg[i + 1]
     elseif _G.arg[i] == '--version' then
-      args.version = _G.arg[i+1]
+      args.version = _G.arg[i + 1]
     elseif _G.arg[i] == '--commit' then
-      args.commit = _G.arg[i+1]
+      args.commit = _G.arg[i + 1]
     elseif _G.arg[i] == '--head' then
       args.head = true
     end
diff --git a/scripts/cdoc_grammar.lua b/scripts/cdoc_grammar.lua
new file mode 100644
index 0000000000..6a7610883b
--- /dev/null
+++ b/scripts/cdoc_grammar.lua
@@ -0,0 +1,87 @@
+--[[!
+LPEG grammar for C doc comments
+]]
+
+--- @class nvim.cdoc.Param
+--- @field kind 'param'
+--- @field name string
+--- @field desc? string
+
+--- @class nvim.cdoc.Return
+--- @field kind 'return'
+--- @field desc string
+
+--- @class nvim.cdoc.Note
+--- @field desc? string
+
+--- @alias nvim.cdoc.grammar.result
+--- | nvim.cdoc.Param
+--- | nvim.cdoc.Return
+--- | nvim.cdoc.Note
+
+--- @class nvim.cdoc.grammar
+--- @field match fun(self, input: string): nvim.cdoc.grammar.result?
+
+local lpeg = vim.lpeg
+local P, R, S = lpeg.P, lpeg.R, lpeg.S
+local Ct, Cg = lpeg.Ct, lpeg.Cg
+
+--- @param x vim.lpeg.Pattern
+local function rep(x)
+  return x ^ 0
+end
+
+--- @param x vim.lpeg.Pattern
+local function rep1(x)
+  return x ^ 1
+end
+
+--- @param x vim.lpeg.Pattern
+local function opt(x)
+  return x ^ -1
+end
+
+local nl = P('\r\n') + P('\n')
+local ws = rep1(S(' \t') + nl)
+
+local any = P(1) -- (consume one character)
+local letter = R('az', 'AZ') + S('_$')
+local ident = letter * rep(letter + R('09'))
+
+local io = P('[') * (P('in') + P('out') + P('inout')) * P(']')
+
+--- @param x string
+local function Pf(x)
+  return opt(ws) * P(x) * opt(ws)
+end
+
+--- @type table<string,vim.lpeg.Pattern>
+local v = setmetatable({}, {
+  __index = function(_, k)
+    return lpeg.V(k)
+  end,
+})
+
+local grammar = P {
+  rep1(P('@') * v.ats),
+
+  ats = v.at_param + v.at_return + v.at_deprecated + v.at_see + v.at_brief + v.at_note + v.at_nodoc,
+
+  at_param = Ct(
+    Cg(P('param'), 'kind') * opt(io) * ws * Cg(ident, 'name') * opt(ws * Cg(rep(any), 'desc'))
+  ),
+
+  at_return = Ct(Cg(P('return'), 'kind') * opt(S('s')) * opt(ws * Cg(rep(any), 'desc'))),
+
+  at_deprecated = Ct(Cg(P('deprecated'), 'kind')),
+
+  at_see = Ct(Cg(P('see'), 'kind') * ws * opt(Pf('#')) * Cg(rep(any), 'desc')),
+
+  at_brief = Ct(Cg(P('brief'), 'kind') * ws * Cg(rep(any), 'desc')),
+
+  at_note = Ct(Cg(P('note'), 'kind') * ws * Cg(rep(any), 'desc')),
+
+  at_nodoc = Ct(Cg(P('nodoc'), 'kind')),
+}
+
+return grammar --[[@as nvim.cdoc.grammar]]
diff --git a/scripts/cdoc_parser.lua b/scripts/cdoc_parser.lua
new file mode 100644
index 0000000000..5f0dc7be2c
--- /dev/null
+++ b/scripts/cdoc_parser.lua
@@ -0,0 +1,223 @@
+local cdoc_grammar = require('scripts.cdoc_grammar')
+local c_grammar = require('src.nvim.generators.c_grammar')
+
+--- @class nvim.cdoc.parser.param
+--- @field name string
+--- @field type string
+--- @field desc string
+
+--- @class nvim.cdoc.parser.return
+--- @field name string
+--- @field type string
+--- @field desc string
+
+--- @class nvim.cdoc.parser.note
+--- @field desc string
+
+--- @class nvim.cdoc.parser.brief
+--- @field kind 'brief'
+--- @field desc string
+
+--- @class nvim.cdoc.parser.fun
+--- @field name string
+--- @field params nvim.cdoc.parser.param[]
+--- @field returns nvim.cdoc.parser.return[]
+--- @field desc string
+--- @field deprecated? true
+--- @field since? string
+--- @field attrs? string[]
+--- @field nodoc? true
+--- @field notes? nvim.cdoc.parser.note[]
+--- @field see? nvim.cdoc.parser.note[]
+
+--- @class nvim.cdoc.parser.State
+--- @field doc_lines? string[]
+--- @field cur_obj? nvim.cdoc.parser.obj
+--- @field last_doc_item? nvim.cdoc.parser.param|nvim.cdoc.parser.return|nvim.cdoc.parser.note
+--- @field last_doc_item_indent? integer
+
+--- @alias nvim.cdoc.parser.obj
+--- | nvim.cdoc.parser.fun
+--- | nvim.cdoc.parser.brief
+
+--- If we collected any `---` lines. Add them to the existing (or new) object
+--- Used for function/class descriptions and multiline param descriptions.
+--- @param state nvim.cdoc.parser.State
+local function add_doc_lines_to_obj(state)
+  if state.doc_lines then
+    state.cur_obj = state.cur_obj or {}
+    local cur_obj = assert(state.cur_obj)
+    local txt = table.concat(state.doc_lines, '\n')
+    if cur_obj.desc then
+      cur_obj.desc = cur_obj.desc .. '\n' .. txt
+    else
+      cur_obj.desc = txt
+    end
+    state.doc_lines = nil
+  end
+end
+
+--- @param line string
+--- @param state nvim.cdoc.parser.State
+local function process_doc_line(line, state)
+  line = line:gsub('^%s+@', '@')
+
+  local parsed = cdoc_grammar:match(line)
+
+  if not parsed then
+    if line:match('^ ') then
+      line = line:sub(2)
+    end
+
+    if state.last_doc_item then
+      if not state.last_doc_item_indent then
+        state.last_doc_item_indent = #line:match('^%s*') + 1
+      end
+      state.last_doc_item.desc = (state.last_doc_item.desc or '')
+        .. '\n'
+        .. line:sub(state.last_doc_item_indent or 1)
+    else
+      state.doc_lines = state.doc_lines or {}
+      table.insert(state.doc_lines, line)
+    end
+    return
+  end
+
+  state.last_doc_item_indent = nil
+  state.last_doc_item = nil
+
+  local kind = parsed.kind
+
+  state.cur_obj = state.cur_obj or {}
+  local cur_obj = assert(state.cur_obj)
+
+  if kind == 'brief' then
+    state.cur_obj = {
+      kind = 'brief',
+      desc = parsed.desc,
+    }
+  elseif kind == 'param' then
+    state.last_doc_item_indent = nil
+    cur_obj.params = cur_obj.params or {}
+    state.last_doc_item = {
+      name = parsed.name,
+      desc = parsed.desc,
+    }
+    table.insert(cur_obj.params, state.last_doc_item)
+  elseif kind == 'return' then
+    cur_obj.returns = { {
+      desc = parsed.desc,
+    } }
+    state.last_doc_item_indent = nil
+    state.last_doc_item = cur_obj.returns[1]
+  elseif kind == 'deprecated' then
+    cur_obj.deprecated = true
+  elseif kind == 'nodoc' then
+    cur_obj.nodoc = true
+  elseif kind == 'since' then
+    cur_obj.since = parsed.desc
+  elseif kind == 'see' then
+    cur_obj.see = cur_obj.see or {}
+    table.insert(cur_obj.see, { desc = parsed.desc })
+  elseif kind == 'note' then
+    state.last_doc_item_indent = nil
+    state.last_doc_item = {
+      desc = parsed.desc,
+    }
+    cur_obj.notes = cur_obj.notes or {}
+    table.insert(cur_obj.notes, state.last_doc_item)
+  else
+    error('Unhandled' .. vim.inspect(parsed))
+  end
+end
+
+--- @param item table
+--- @param state nvim.cdoc.parser.State
+local function process_proto(item, state)
+  state.cur_obj = state.cur_obj or {}
+  local cur_obj = assert(state.cur_obj)
+  cur_obj.name = item.name
+  cur_obj.params = cur_obj.params or {}
+
+  for _, p in ipairs(item.parameters) do
+    local param = { name = p[2], type = p[1] }
+    local added = false
+    for _, cp in ipairs(cur_obj.params) do
+      if cp.name == param.name then
+        cp.type = param.type
+        added = true
+        break
+      end
+    end
+
+    if not added then
+      table.insert(cur_obj.params, param)
+    end
+  end
+
+  cur_obj.returns = cur_obj.returns or { {} }
+  cur_obj.returns[1].type = item.return_type
+
+  for _, a in ipairs({
+    'fast',
+    'remote_only',
+    'lua_only',
+    'textlock',
+    'textlock_allow_cmdwin',
+  }) do
+    if item[a] then
+      cur_obj.attrs = cur_obj.attrs or {}
+      table.insert(cur_obj.attrs, a)
+    end
+  end
+
+  cur_obj.deprecated_since = item.deprecated_since
+
+  -- Remove some arguments
+  for i = #cur_obj.params, 1, -1 do
+    local p = cur_obj.params[i]
+    if p.name == 'channel_id' or vim.tbl_contains({ 'lstate', 'arena', 'error' }, p.type) then
+      table.remove(cur_obj.params, i)
+    end
+  end
+end
+
+local M = {}
+
+--- @param filename string
+--- @return {} classes
+--- @return nvim.cdoc.parser.fun[] funs
+--- @return string[] briefs
+function M.parse(filename)
+  local funs = {} --- @type nvim.cdoc.parser.fun[]
+  local briefs = {} --- @type string[]
+  local state = {} --- @type nvim.cdoc.parser.State
+
+  local txt = assert(io.open(filename, 'r')):read('*all')
+
+  local parsed = c_grammar.grammar:match(txt)
+  for _, item in ipairs(parsed) do
+    if item.comment then
+      process_doc_line(item.comment, state)
+    else
+      add_doc_lines_to_obj(state)
+      if item[1] == 'proto' then
+        process_proto(item, state)
+        table.insert(funs, state.cur_obj)
+      end
+      local cur_obj = state.cur_obj
+      if cur_obj and not item.static then
+        if cur_obj.kind == 'brief' then
+          table.insert(briefs, cur_obj.desc)
+        end
+      end
+      state = {}
+    end
+  end
+
+  return {}, funs, briefs
+end
+
+-- M.parse('src/nvim/api/vim.c')
+
+return M
diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index e331dd996e..f1bba5c0a2 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -1,7 +1,8 @@
+#!/usr/bin/env -S nvim -l
+
 -- Generator for various vimdoc and Lua type files
 
-local DEP_API_METADATA = 'build/api_metadata.mpack'
-local DEP_API_DOC  = 'runtime/doc/api.mpack'
+local DEP_API_METADATA = 'build/funcs_metadata.mpack'
 
 --- @class vim.api.metadata
 --- @field name string
@@ -17,6 +18,31 @@ local DEP_API_DOC  = 'runtime/doc/api.mpack'
 --- @field remote boolean
 --- @field since integer
 
+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_extmarks = 'vim.api.keyset.get_extmark_item[]',
+  nvim_buf_get_keymap = 'vim.api.keyset.keymap[]',
+  nvim_get_autocmds = 'vim.api.keyset.get_autocmds.ret[]',
+  nvim_get_color_map = 'table<string,integer>',
+  nvim_get_command = 'table<string,vim.api.keyset.command_info>',
+  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
+  -- 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',
+
+  nvim_get_mode = 'vim.api.keyset.get_mode',
+  nvim_get_namespaces = 'table<string,integer>',
+  nvim_get_option_info = 'vim.api.keyset.get_option_info',
+  nvim_get_option_info2 = 'vim.api.keyset.get_option_info',
+  nvim_parse_cmd = 'vim.api.keyset.parse_cmd',
+  nvim_win_get_config = 'vim.api.keyset.win_config',
+}
+
 local LUA_META_HEADER = {
   '--- @meta _',
   '-- THIS FILE IS GENERATED',
@@ -48,6 +74,16 @@ local LUA_OPTION_META_HEADER = {
   'vim.wo = vim.wo',
 }
 
+local LUA_VVAR_META_HEADER = {
+  '--- @meta _',
+  '-- THIS FILE IS GENERATED',
+  '-- DO NOT EDIT',
+  "error('Cannot require a meta file')",
+  '',
+  '--- @class vim.v',
+  'vim.v = ...',
+}
+
 local LUA_KEYWORDS = {
   ['and'] = true,
   ['end'] = true,
@@ -56,10 +92,12 @@ local LUA_KEYWORDS = {
   ['if'] = true,
   ['while'] = true,
   ['repeat'] = true,
+  ['true'] = true,
+  ['false'] = true,
 }
 
 local OPTION_TYPES = {
-  bool = 'boolean',
+  boolean = 'boolean',
   number = 'integer',
   string = 'string',
 }
@@ -76,6 +114,7 @@ local API_TYPES = {
   LuaRef = 'function',
   Dictionary = 'table<string,any>',
   Float = 'number',
+  HLGroupID = 'number|string',
   void = '',
 }
 
@@ -170,44 +209,65 @@ end
 
 --- @return table<string, vim.EvalFn>
 local function get_api_meta()
-  local mpack_f = assert(io.open(DEP_API_METADATA, 'rb'))
-  local metadata = vim.mpack.decode(mpack_f:read('*all')) --[[@as vim.api.metadata[] ]]
   local ret = {} --- @type table<string, vim.EvalFn>
 
-  local doc_mpack_f = assert(io.open(DEP_API_DOC, 'rb'))
-  local doc_metadata = vim.mpack.decode(doc_mpack_f:read('*all')) --[[@as table<string,vim.gen_vim_doc_fun>]]
-
-  for _, fun in ipairs(metadata) do
-    if fun.lua then
-      local fdoc = doc_metadata[fun.name]
-
-      local params = {} --- @type {[1]:string,[2]:string}[]
-      for _, p in ipairs(fun.parameters) do
-        local ptype, pname = p[1], p[2]
-        params[#params + 1] = {
-          pname,
-          api_type(ptype),
-          fdoc and fdoc.parameters_doc[pname] or nil,
-        }
-      end
+  local cdoc_parser = require('scripts.cdoc_parser')
 
-      local r = {
-        signature = 'NA',
-        name = fun.name,
-        params = params,
-        returns = api_type(fun.return_type),
-        deprecated = fun.deprecated_since ~= nil,
-      }
+  local f = 'src/nvim/api'
 
-      if fdoc then
-        if #fdoc.doc > 0 then
-          r.desc = table.concat(fdoc.doc, '\n')
+  local function include(fun)
+    if not vim.startswith(fun.name, 'nvim_') then
+      return false
+    end
+    if vim.tbl_contains(fun.attrs or {}, 'lua_only') then
+      return true
+    end
+    if vim.tbl_contains(fun.attrs or {}, 'remote_only') then
+      return false
+    end
+    return true
+  end
+
+  --- @type table<string,nvim.cdoc.parser.fun>
+  local functions = {}
+  for path, ty in vim.fs.dir(f) do
+    if ty == 'file' then
+      local filename = vim.fs.joinpath(f, path)
+      local _, funs = cdoc_parser.parse(filename)
+      for _, fn in ipairs(funs) do
+        if include(fn) then
+          functions[fn.name] = fn
         end
-        r.return_desc = (fdoc['return'] or {})[1]
       end
+    end
+  end
 
-      ret[fun.name] = r
+  for _, fun in pairs(functions) do
+    local deprecated = fun.deprecated_since ~= nil
+
+    local params = {} --- @type {[1]:string,[2]:string}[]
+    for _, p in ipairs(fun.params) do
+      params[#params + 1] = {
+        p.name,
+        api_type(p.type),
+        not deprecated and p.desc or nil,
+      }
     end
+
+    local r = {
+      signature = 'NA',
+      name = fun.name,
+      params = params,
+      returns = api_type(fun.returns[1].type),
+      deprecated = deprecated,
+    }
+
+    if not deprecated then
+      r.desc = fun.desc
+      r.return_desc = fun.returns[1].desc
+    end
+
+    ret[fun.name] = r
   end
   return ret
 end
@@ -235,12 +295,10 @@ end
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
 local function render_api_meta(_f, fun, write)
-  if not vim.startswith(fun.name, 'nvim_') then
-    return
-  end
-
   write('')
 
+  local text_utils = require('scripts.text_utils')
+
   if vim.startswith(fun.name, 'nvim__') then
     write('--- @private')
   end
@@ -251,10 +309,10 @@ 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)
     for _, l in ipairs(split(norm_text(desc))) do
       write('--- ' .. l)
     end
-    write('---')
   end
 
   local param_names = {} --- @type string[]
@@ -263,8 +321,11 @@ local function render_api_meta(_f, fun, write)
     param_names[#param_names + 1] = p[1]
     local pdesc = p[3]
     if pdesc then
-      local pdesc_a = split(norm_text(pdesc))
-      write('--- @param ' .. p[1] .. ' ' .. p[2] .. ' ' .. pdesc_a[1])
+      local s = '--- @param ' .. p[1] .. ' ' .. p[2] .. ' '
+      local indent = #('@param ' .. p[1] .. ' ')
+      pdesc = text_utils.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
         if not pdesc_a[i] then
           break
@@ -276,11 +337,10 @@ local function render_api_meta(_f, fun, write)
     end
   end
   if fun.returns ~= '' then
-    if fun.returns_desc then
-      write('--- @return ' .. fun.returns .. ' : ' .. fun.returns_desc)
-    else
-      write('--- @return ' .. fun.returns)
-    end
+    local ret_desc = fun.returns_desc and ' : ' .. fun.returns_desc or ''
+    ret_desc = text_utils.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
   local param_str = table.concat(param_names, ', ')
 
@@ -290,8 +350,6 @@ end
 --- @return table<string, vim.EvalFn>
 local function get_api_keysets_meta()
   local mpack_f = assert(io.open(DEP_API_METADATA, 'rb'))
-
-  --- @diagnostic disable-next-line:no-unknown
   local metadata = assert(vim.mpack.decode(mpack_f:read('*all')))
 
   local ret = {} --- @type table<string, vim.EvalFn>
@@ -302,7 +360,7 @@ local function get_api_keysets_meta()
   for _, k in ipairs(keysets) do
     local params = {}
     for _, key in ipairs(k.keys) do
-      table.insert(params, {key..'?', api_type(k.types[key] or 'any')})
+      table.insert(params, { key .. '?', api_type(k.types[key] or 'any') })
     end
     ret[k.name] = {
       signature = 'NA',
@@ -342,50 +400,45 @@ local function render_eval_meta(f, fun, write)
 
   local params = process_params(fun.params)
 
-  if fun.signature then
-    write('')
-    if fun.deprecated then
-      write('--- @deprecated')
-    end
-
-    local desc = fun.desc
-
-    if desc then
-      --- @type string
-      desc = desc:gsub('\n%s*\n%s*$', '\n')
-      for _, l in ipairs(split(desc)) do
-        l = l:gsub('^      ', ''):gsub('\t', '  '):gsub('@', '\\@')
-        write('--- ' .. l)
-      end
-    end
+  write('')
+  if fun.deprecated then
+    write('--- @deprecated')
+  end
 
-    local req_args = type(fun.args) == 'table' and fun.args[1] or fun.args or 0
+  local desc = fun.desc
 
-    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))
+  if desc then
+    --- @type string
+    desc = desc:gsub('\n%s*\n%s*$', '\n')
+    for _, l in ipairs(split(desc)) do
+      l = l:gsub('^      ', ''):gsub('\t', '  '):gsub('@', '\\@')
+      write('--- ' .. l)
     end
+  end
 
-    if fun.returns ~= false then
-      write('--- @return ' .. (fun.returns or 'any'))
-    end
+  local req_args = type(fun.args) == 'table' and fun.args[1] or fun.args or 0
 
-    write(render_fun_sig(funname, params))
+  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))
+  end
 
-    return
+  if fun.returns ~= false then
+    write('--- @return ' .. (fun.returns or 'any'))
   end
 
-  print('no doc for', funname)
+  write(render_fun_sig(funname, params))
 end
 
---- @type table<string,true>
-local rendered_tags = {}
-
 --- @param name string
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
 local function render_sig_and_tag(name, fun, write)
+  if not fun.signature then
+    return
+  end
+
   local tags = { '*' .. name .. '()*' }
 
   if fun.tags then
@@ -396,7 +449,7 @@ local function render_sig_and_tag(name, fun, write)
 
   local tag = table.concat(tags, ' ')
   local siglen = #fun.signature
-  local conceal_offset = 2*(#tags - 1)
+  local conceal_offset = 2 * (#tags - 1)
   local tag_pad_len = math.max(1, 80 - #tag + conceal_offset)
 
   if siglen + #tag > 80 then
@@ -419,24 +472,17 @@ local function render_eval_doc(f, fun, write)
     return
   end
 
-  local desc = fun.desc
-
-  if not desc then
+  if f:find('__%d+$') then
     write(fun.signature)
-    return
+  else
+    render_sig_and_tag(fun.name or f, fun, write)
   end
 
-  local name = fun.name or f
-
-  if rendered_tags[name] then
-    write(fun.signature)
-  else
-    render_sig_and_tag(name, fun, write)
-    rendered_tags[name] = true
+  if not fun.desc then
+    return
   end
 
-  desc = vim.trim(desc)
-  local desc_l = split(desc)
+  local desc_l = split(vim.trim(fun.desc))
   for _, l in ipairs(desc_l) do
     l = l:gsub('^      ', '')
     if vim.startswith(l, '<') and not l:match('^<[^ \t]+>') then
@@ -473,7 +519,7 @@ local function render_option_default(d, vimdoc)
     end
   end
 
-  if dt == "" or dt == nil or type(dt) == 'function' then
+  if dt == '' or dt == nil or type(dt) == 'function' then
     dt = d.meta
   end
 
@@ -481,22 +527,22 @@ local function render_option_default(d, vimdoc)
   if not vimdoc then
     v = vim.inspect(dt) --[[@as string]]
   else
-    v = type(dt) == 'string' and '"'..dt..'"' or tostring(dt)
+    v = type(dt) == 'string' and '"' .. dt .. '"' or tostring(dt)
   end
 
   --- @type table<string, string|false>
   local envvars = {
     TMPDIR = false,
     VIMRUNTIME = false,
-    XDG_CONFIG_HOME = vim.env.HOME..'/.local/config',
-    XDG_DATA_HOME = vim.env.HOME..'/.local/share',
-    XDG_STATE_HOME = vim.env.HOME..'/.local/state',
+    XDG_CONFIG_HOME = vim.env.HOME .. '/.local/config',
+    XDG_DATA_HOME = vim.env.HOME .. '/.local/share',
+    XDG_STATE_HOME = vim.env.HOME .. '/.local/state',
   }
 
   for name, default in pairs(envvars) do
     local value = vim.env[name] or default
     if value then
-      v = v:gsub(vim.pesc(value), '$'..name)
+      v = v:gsub(vim.pesc(value), '$' .. name)
     end
   end
 
@@ -509,31 +555,55 @@ end
 local function render_option_meta(_f, opt, write)
   write('')
   for _, l in ipairs(split(norm_text(opt.desc))) do
-    write('--- '..l)
+    write('--- ' .. l)
   end
 
-  write('--- @type '..OPTION_TYPES[opt.type])
-  write('vim.o.'..opt.full_name..' = '..render_option_default(opt.defaults))
+  write('--- @type ' .. OPTION_TYPES[opt.type])
+  write('vim.o.' .. opt.full_name .. ' = ' .. render_option_default(opt.defaults))
   if opt.abbreviation then
-    write('vim.o.'..opt.abbreviation..' = vim.o.'..opt.full_name)
+    write('vim.o.' .. opt.abbreviation .. ' = vim.o.' .. opt.full_name)
   end
 
   for _, s in pairs {
-    {'wo', 'window'},
-    {'bo', 'buffer'},
-    {'go', 'global'},
+    { 'wo', 'window' },
+    { 'bo', 'buffer' },
+    { 'go', 'global' },
   } do
     local id, scope = s[1], s[2]
     if vim.list_contains(opt.scope, scope) or (id == 'go' and #opt.scope > 1) then
-      local pfx = 'vim.'..id..'.'
-      write(pfx..opt.full_name..' = vim.o.'..opt.full_name)
+      local pfx = 'vim.' .. id .. '.'
+      write(pfx .. opt.full_name .. ' = vim.o.' .. opt.full_name)
       if opt.abbreviation then
-        write(pfx..opt.abbreviation..' = '..pfx..opt.full_name)
+        write(pfx .. opt.abbreviation .. ' = ' .. pfx .. opt.full_name)
       end
     end
   end
 end
 
+--- @param _f string
+--- @param opt vim.option_meta
+--- @param write fun(line: string)
+local function render_vvar_meta(_f, opt, write)
+  write('')
+
+  local desc = split(norm_text(opt.desc))
+  while desc[#desc]:match('^%s*$') do
+    desc[#desc] = nil
+  end
+
+  for _, l in ipairs(desc) do
+    write('--- ' .. l)
+  end
+
+  write('--- @type ' .. (opt.type or 'any'))
+
+  if LUA_KEYWORDS[opt.full_name] then
+    write("vim.v['" .. opt.full_name .. "'] = ...")
+  else
+    write('vim.v.' .. opt.full_name .. ' = ...')
+  end
+end
+
 --- @param s string[]
 --- @return string
 local function scope_to_doc(s)
@@ -541,14 +611,14 @@ local function scope_to_doc(s)
     global = 'global',
     buffer = 'local to buffer',
     window = 'local to window',
-    tab = 'local to tab page'
+    tab = 'local to tab page',
   }
 
   if #s == 1 then
     return m[s[1]]
   end
   assert(s[1] == 'global')
-  return 'global or '..m[s[2]]..' |global-local|'
+  return 'global or ' .. m[s[2]] .. ' |global-local|'
 end
 
 -- @param o vim.option_meta
@@ -574,6 +644,21 @@ local function scope_more_doc(o)
   return ''
 end
 
+--- @param x string
+--- @return string
+local function dedent(x)
+  local xs = split(x)
+  local leading_ws = xs[1]:match('^%s*') --[[@as string]]
+  local leading_ws_pat = '^' .. leading_ws
+
+  for i in ipairs(xs) do
+    local strip_pat = xs[i]:match(leading_ws_pat) and leading_ws_pat or '^%s*'
+    xs[i] = xs[i]:gsub(strip_pat, '')
+  end
+
+  return table.concat(xs, '\n')
+end
+
 --- @return table<string,vim.option_meta>
 local function get_option_meta()
   local opts = require('src/nvim/options').options
@@ -596,29 +681,41 @@ local function get_option_meta()
   return ret
 end
 
+--- @return table<string,vim.option_meta>
+local function get_vvar_meta()
+  local info = require('src/nvim/vvars').vars
+  local ret = {} --- @type table<string,vim.option_meta>
+  for name, o in pairs(info) do
+    o.desc = dedent(o.desc)
+    o.full_name = name
+    ret[name] = o
+  end
+  return ret
+end
+
 --- @param opt vim.option_meta
 --- @return string[]
 local function build_option_tags(opt)
   --- @type string[]
   local tags = { opt.full_name }
 
-  tags[#tags+1] = opt.abbreviation
-  if opt.type == 'bool' then
+  tags[#tags + 1] = opt.abbreviation
+  if opt.type == 'boolean' then
     for i = 1, #tags do
-      tags[#tags+1] = 'no'..tags[i]
+      tags[#tags + 1] = 'no' .. tags[i]
     end
   end
 
   for i, t in ipairs(tags) do
-    tags[i] = "'"..t.."'"
+    tags[i] = "'" .. t .. "'"
   end
 
   for _, t in ipairs(opt.tags or {}) do
-    tags[#tags+1] = t
+    tags[#tags + 1] = t
   end
 
   for i, t in ipairs(tags) do
-    tags[i] = "*"..t.."*"
+    tags[i] = '*' .. t .. '*'
   end
 
   return tags
@@ -630,10 +727,10 @@ end
 local function render_option_doc(_f, opt, write)
   local tags = build_option_tags(opt)
   local tag_str =