feat(docs): replace lua2dox.lua

Problem:

The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.

Solution:

Re-implement the flow using Lua, LPEG and treesitter.

- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
  - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
  - LPEG for C parsing (see `scripts/cdoc_parser.lua`)
  - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
  - Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
   - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).

9 files changed, 2135 insertions, 2350 deletions

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 b7f17a2d58..895033d5af 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -3,7 +3,6 @@
 -- Generator for various vimdoc and Lua type files
 
 local DEP_API_METADATA = 'build/api_metadata.mpack'
-local DEP_API_DOC = 'runtime/doc/api.mpack'
 
 --- @class vim.api.metadata
 --- @field name string
@@ -210,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
+
+  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,
+    }
 
-      ret[fun.name] = r
+    if not deprecated then
+      r.desc = fun.desc
+      r.return_desc = fun.returns[1].desc
     end
+
+    ret[fun.name] = r
   end
   return ret
 end
@@ -275,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
@@ -291,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[]
@@ -303,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
@@ -317,6 +338,7 @@ 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 = 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
@@ -328,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>
diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua
new file mode 100755
index 0000000000..290cd83fbc
--- /dev/null
+++ b/scripts/gen_vimdoc.lua
@@ -0,0 +1,787 @@
+#!/usr/bin/env -S nvim -l
+--- Generates Nvim :help docs from Lua/C docstrings
+---
+--- The generated :help text for each function is formatted as follows:
+--- - Max width of 78 columns (`TEXT_WIDTH`).
+--- - Indent with spaces (not tabs).
+--- - Indent of 4 columns for body text (`INDENTATION`).
+--- - Function signature and helptag (right-aligned) on the same line.
+---   - Signature and helptag must have a minimum of 8 spaces between them.
+---   - If the signature is too long, it is placed on the line after the helptag.
+---     Signature wraps with subsequent lines indented to the open parenthesis.
+---   - Subsection bodies are indented an additional 4 spaces.
+--- - Body consists of function description, parameters, return description, and
+---   C declaration (`INCLUDE_C_DECL`).
+--- - Parameters are omitted for the `void` and `Error *` types, or if the
+---   parameter is marked as [out].
+--- - Each function documentation is separated by a single line.
+
+local luacats_parser = require('scripts.luacats_parser')
+local cdoc_parser = require('scripts.cdoc_parser')
+local text_utils = require('scripts.text_utils')
+
+local fmt = string.format
+
+local wrap = text_utils.wrap
+local md_to_vimdoc = text_utils.md_to_vimdoc
+
+local TEXT_WIDTH = 78
+local INDENTATION = 4
+
+--- @class (exact) nvim.gen_vimdoc.Config
+---
+--- Generated documentation target, e.g. api.txt
+--- @field filename string
+---
+--- @field section_order string[]
+---
+--- List of files/directories for doxygen to read, relative to `base_dir`.
+--- @field files string[]
+---
+--- @field exclude_types? true
+---
+--- Section name overrides. Key: filename (e.g., vim.c)
+--- @field section_name? table<string,string>
+---
+--- @field fn_name_pat? string
+---
+--- @field fn_xform? fun(fun: nvim.luacats.parser.fun)
+---
+--- For generated section names.
+--- @field section_fmt fun(name: string): string
+---
+--- @field helptag_fmt fun(name: string): string
+---
+--- Per-function helptag.
+--- @field fn_helptag_fmt? fun(fun: nvim.luacats.parser.fun): string
+---
+--- @field append_only? string[]
+
+local function contains(t, xs)
+  return vim.tbl_contains(xs, t)
+end
+
+--- @type {level:integer, prerelease:boolean}?
+local nvim_api_info_
+
+--- @return {level: integer, prerelease:boolean}
+local function nvim_api_info()
+  if not nvim_api_info_ then
+    --- @type integer?, boolean?
+    local level, prerelease
+    for l in io.lines('CMakeLists.txt') do
+      --- @cast l string
+      if level and prerelease then
+        break
+      end
+      local m1 = l:match('^set%(NVIM_API_LEVEL%s+(%d+)%)')
+      if m1 then
+        level = tonumber(m1) --[[@as integer]]
+      end
+      local m2 = l:match('^set%(NVIM_API_PRERELEASE%s+(%w+)%)')
+      if m2 then
+        prerelease = m2 == 'true'
+      end
+    end
+    nvim_api_info_ = { level = level, prerelease = prerelease }
+  end
+
+  return nvim_api_info_
+end
+
+--- @param fun nvim.luacats.parser.fun
+--- @return string
+local function fn_helptag_fmt_common(fun)
+  local fn_sfx = fun.table and '' or '()'
+  if fun.classvar then
+    return fmt('*%s:%s%s*', fun.classvar, fun.name, fn_sfx)
+  end
+  if fun.module then
+    return fmt('*%s.%s%s*', fun.module, fun.name, fn_sfx)
+  end
+  return fmt('*%s%s*', fun.name, fn_sfx)
+end
+
+--- @type table<string,nvim.gen_vimdoc.Config>
+local config = {
+  api = {
+    filename = 'api.txt',
+    section_order = {
+      'vim.c',
+      'vimscript.c',
+      'command.c',
+      'options.c',
+      'buffer.c',
+      'extmark.c',
+      'window.c',
+      'win_config.c',
+      'tabpage.c',
+      'autocmd.c',
+      'ui.c',
+    },
+    exclude_types = true,
+    fn_name_pat = 'nvim_.*',
+    files = { 'src/nvim/api' },
+    section_name = {
+      ['vim.c'] = 'Global',
+    },
+    section_fmt = function(name)
+      return name .. ' Functions'
+    end,
+    helptag_fmt = function(name)
+      return fmt('*api-%s*', name:lower())
+    end,
+  },
+  lua = {
+    filename = 'lua.txt',
+    section_order = {
+      'highlight.lua',
+      'diff.lua',
+      'mpack.lua',
+      'json.lua',
+      'base64.lua',
+      'spell.lua',
+      'builtin.lua',
+      '_options.lua',
+      '_editor.lua',
+      '_inspector.lua',
+      'shared.lua',
+      'loader.lua',
+      'uri.lua',
+      'ui.lua',
+      'filetype.lua',
+      'keymap.lua',
+      'fs.lua',
+      'glob.lua',
+      'lpeg.lua',
+      're.lua',
+      'regex.lua',
+      'secure.lua',
+      'version.lua',
+      'iter.lua',
+      'snippet.lua',
+      'text.lua',
+    },
+    files = {
+      'runtime/lua/vim/iter.lua',
+      'runtime/lua/vim/_editor.lua',
+      'runtime/lua/vim/_options.lua',
+      'runtime/lua/vim/shared.lua',
+      'runtime/lua/vim/loader.lua',
+      'runtime/lua/vim/uri.lua',
+      'runtime/lua/vim/ui.lua',
+      'runtime/lua/vim/filetype.lua',
+      'runtime/lua/vim/keymap.lua',
+      'runtime/lua/vim/fs.lua',
+      'runtime/lua/vim/highlight.lua',
+      'runtime/lua/vim/secure.lua',
+      'runtime/lua/vim/version.lua',
+      'runtime/lua/vim/_inspector.lua',
+      'runtime/lua/vim/snippet.lua',
+      'runtime/lua/vim/text.lua',
+      'runtime/lua/vim/glob.lua',
+      'runtime/lua/vim/_meta/builtin.lua',
+      'runtime/lua/vim/_meta/diff.lua',
+      'runtime/lua/vim/_meta/mpack.lua',
+      'runtime/lua/vim/_meta/json.lua',
+      'runtime/lua/vim/_meta/base64.lua',
+      'runtime/lua/vim/_meta/regex.lua',
+      'runtime/lua/vim/_meta/lpeg.lua',
+      'runtime/lua/vim/_meta/re.lua',
+      'runtime/lua/vim/_meta/spell.lua',
+    },
+    fn_xform = function(fun)
+      if contains(fun.module, { 'vim.uri', 'vim.shared', 'vim._editor' }) then
+        fun.module = 'vim'
+      end
+
+      if fun.module == 'vim' and contains(fun.name, { 'cmd', 'inspect' }) then
+        fun.table = nil
+      end
+
+      if fun.classvar or vim.startswith(fun.name, 'vim.') or fun.module == 'vim.iter' then
+        return
+      end
+
+      fun.name = fmt('%s.%s', fun.module, fun.name)
+    end,
+    section_name = {
+      ['_inspector.lua'] = 'inspector',
+    },
+    section_fmt = function(name)
+      name = name:lower()
+      if name == '_editor' then
+        return 'Lua module: vim'
+      elseif name == '_options' then
+        return 'LUA-VIMSCRIPT BRIDGE'
+      elseif name == 'builtin' then
+        return 'VIM'
+      end
+      if
+        contains(name, {
+          'highlight',
+          'mpack',
+          'json',
+          'base64',
+          'diff',
+          'spell',
+          'regex',
+          'lpeg',
+          're',
+        })
+      then
+        return 'VIM.' .. name:upper()
+      end
+      return 'Lua module: vim.' .. name
+    end,
+    helptag_fmt = function(name)
+      if name == '_editor' then
+        return '*lua-vim*'
+      elseif name == '_options' then
+        return '*lua-vimscript*'
+      end
+      return '*vim.' .. name:lower() .. '*'
+    end,
+    fn_helptag_fmt = function(fun)
+      local name = fun.name
+
+      if vim.startswith(name, 'vim.') then
+        local fn_sfx = fun.table and '' or '()'
+        return fmt('*%s%s*', name, fn_sfx)
+      elseif fun.classvar == 'Option' then
+        return fmt('*vim.opt:%s()*', name)
+      end
+
+      return fn_helptag_fmt_common(fun)
+    end,
+    append_only = {
+      'shared.lua',
+    },
+  },
+  lsp = {
+    filename = 'lsp.txt',
+    section_order = {
+      'lsp.lua',
+      'buf.lua',
+      'diagnostic.lua',
+      'codelens.lua',
+      'inlay_hint.lua',
+      'tagfunc.lua',
+      'semantic_tokens.lua',
+      'handlers.lua',
+      'util.lua',
+      'log.lua',
+      'rpc.lua',
+      'protocol.lua',
+    },
+    files = {
+      'runtime/lua/vim/lsp',
+      'runtime/lua/vim/lsp.lua',
+    },
+    fn_xform = function(fun)
+      fun.name = fun.name:gsub('result%.', '')
+    end,
+    section_fmt = function(name)
+      if name:lower() == 'lsp' then
+        return 'Lua module: vim.lsp'
+      end
+      return 'Lua module: vim.lsp.' .. name:lower()
+    end,
+    helptag_fmt = function(name)
+      if name:lower() == 'lsp' then
+        return '*lsp-core*'
+      end
+      return fmt('*lsp-%s*', name:lower())
+    end,
+  },
+  diagnostic = {
+    filename = 'diagnostic.txt',
+    section_order = {
+      'diagnostic.lua',
+    },
+    files = { 'runtime/lua/vim/diagnostic.lua' },
+    section_fmt = function()
+      return 'Lua module: vim.diagnostic'
+    end,
+    helptag_fmt = function()
+      return '*diagnostic-api*'
+    end,
+  },
+  treesitter = {
+    filename = 'treesitter.txt',
+    section_order = {
+      'treesitter.lua',
+      'language.lua',
+      'query.lua',
+      'highlighter.lua',
+      'languagetree.lua',
+      'dev.lua',
+    },
+    files = {
+      'runtime/lua/vim/treesitter.lua',
+      'runtime/lua/vim/treesitter/',
+    },
+    section_fmt = function(name)
+      if name:lower() == 'treesitter' then
+        return 'Lua module: vim.treesitter'
+      end
+      return 'Lua module: vim.treesitter.' .. name:lower()
+    end,
+    helptag_fmt = function(name)
+      if name:lower() == 'treesitter' then
+        return '*lua-treesitter-core*'
+      end
+      return '*lua-treesitter-' .. name:lower() .. '*'
+    end,
+  },
+}
+
+--- @param ty string
+--- @param generics table<string,string>
+--- @return string
+local function replace_generics(ty, generics)
+  if ty:sub(-2) == '[]' then
+    local ty0 = ty:sub(1, -3)
+    if generics[ty0] then
+      return generics[ty0] .. '[]'
+    end
+  elseif ty:sub(-1) == '?' then
+    local ty0 = ty:sub(1, -2)
+    if generics[ty0] then
+      return generics[ty0] .. '?'
+    end
+  end
+
+  return generics[ty] or ty
+end
+
+--- @param ty string
+--- @param generics? table<string,string>
+local function render_type(ty, generics)
+  if generics then
+    ty = replace_generics(ty, generics)
+  end
+  ty = ty:gsub('%s*|%s*nil', '?')
+  ty = ty:gsub('nil%s*|%s*(.*)', '%1?')
+  ty = ty:gsub('%s*|%s*', '|')
+  return fmt('(`%s`)', ty)
+end
+
+--- @param p nvim.luacats.parser.param|nvim.luacats.parser.field
+local function should_render_param(p)
+  return not p.access and not contains(p.name, { '_', 'self' })
+end
+
+--- @param xs (nvim.luacats.parser.param|nvim.luacats.parser.field)[]
+--- @param generics? table<string,string>
+--- @param exclude_types? true
+local function render_fields_or_params(xs, generics, exclude_types)
+  local ret = {} --- @type string[]
+
+  xs = vim.tbl_filter(should_render_param, xs)
+
+  local indent = 0
+  for _, p in ipairs(xs) do
+    if p.type or p.desc then
+      indent = math.max(indent, #p.name + 3)
+    end
+    if exclude_types then
+      p.type = nil
+    end
+  end
+
+  for _, p in ipairs(xs) do
+    local nm, ty = p.name, p.type
+    local desc = p.desc
+    local pnm = fmt('      • %-' .. indent .. 's', '{' .. nm .. '}')
+    if ty then
+      local pty = render_type(ty, generics)
+      if desc then
+        desc = fmt('%s %s', pty, desc)
+        table.insert(ret, pnm)
+        table.insert(ret, md_to_vimdoc(desc, 1, 9 + indent, TEXT_WIDTH, true))
+      else
+        table.insert(ret, fmt('%s %s\n', pnm, pty))
+      end
+    else
+      if desc then
+        table.insert(ret, pnm)
+        table.insert(ret, md_to_vimdoc(desc, 1, 9 + indent, TEXT_WIDTH, true))
+      end
+    end
+  end
+
+  return table.concat(ret)
+end
+
+-- --- @param class lua2vimdoc.class
+-- local function render_class(class)
+--   writeln(fmt('*%s*', class.name))
+--   writeln()
+--   if #class.fields > 0 then
+--     writeln('    Fields: ~')
+--     render_fields_or_params(class.fields)
+--   end
+--   writeln()
+-- end
+
+-- --- @param cls table<string,lua2vimdoc.class>
+-- local function render_classes(cls)
+--   --- @diagnostic disable-next-line:no-unknown
+--   for _, class in vim.spairs(cls) do
+--     render_class(class)
+--   end
+-- end
+
+--- @param fun nvim.luacats.parser.fun
+--- @param cfg nvim.gen_vimdoc.Config
+local function render_fun_header(fun, cfg)
+  local ret = {} --- @type string[]
+
+  local args = {} --- @type string[]
+  for _, p in ipairs(fun.params or {}) do
+    if p.name ~= 'self' then
+      args[#args + 1] = fmt('{%s}', p.name:gsub('%?$', ''))
+    end
+  end
+
+  local nm = fun.name
+  if fun.classvar then
+    nm = fmt('%s:%s', fun.classvar, nm)
+  end
+
+  local proto = fun.table and nm or nm .. '(' .. table.concat(args, ', ') .. ')'
+
+  if not cfg.fn_helptag_fmt then
+    cfg.fn_helptag_fmt = fn_helptag_fmt_common
+  end
+
+  local tag = cfg.fn_helptag_fmt(fun)
+
+  if #proto + #tag > TEXT_WIDTH - 8 then
+    table.insert(ret, fmt('%78s\n', tag))
+    local name, pargs = proto:match('([^(]+%()(.*)')
+    table.insert(ret, name)
+    table.insert(ret, wrap(pargs, 0, #name, TEXT_WIDTH))
+  else
+    local pad = TEXT_WIDTH - #proto - #tag
+    table.insert(ret, proto .. string.rep(' ', pad) .. tag)
+  end
+
+  return table.concat(ret)
+end
+
+--- @param returns nvim.luacats.parser.return[]
+--- @param generics? table<string,string>
+--- @param exclude_types boolean
+local function render_returns(returns, generics, exclude_types)
+  local ret = {} --- @type string[]
+
+  returns = vim.deepcopy(returns)
+  if exclude_types then
+    for _, r in ipairs(returns) do
+      r.type = nil
+    end
+  end
+
+  if #returns > 1 then
+    table.insert(ret, '    Return (multiple): ~\n')
+  elseif #returns == 1 and next(returns[1]) then
+    table.insert(ret, '    Return: ~\n')
+  end
+
+  for _, p in ipairs(returns) do
+    local rnm, ty, desc = p.name, p.type, p.desc
+    local blk = ''
+    if ty then
+      blk = render_type(ty, generics)
+    end
+    if rnm then
+      blk = blk .. ' ' .. rnm
+    end
+    if desc then
+      blk = blk .. ' ' .. desc
+    end
+    table.insert(ret, md_to_vimdoc(blk, 8, 8, TEXT_WIDTH, true))
+  end
+
+  return table.concat(ret)
+end
+
+--- @param fun nvim.luacats.parser.fun
+--- @param cfg nvim.gen_vimdoc.Config
+local function render_fun(fun, cfg)
+  if fun.access or fun.deprecated or fun.nodoc then
+    return
+  end
+
+  if cfg.fn_name_pat and not fun.name:match(cfg.fn_name_pat) then
+    return
+  end
+
+  if vim.startswith(fun.name, '_') or fun.name:find('[:.]_') then
+    return
+  end
+
+  local ret = {} --- @type string[]
+
+  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 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
+  end
+
+  if fun.notes then
+    table.insert(ret, '\n    Note: ~\n')
+    for _, p in ipairs(fun.notes) do
+      table.insert(ret, '      • ' .. md_to_vimdoc(p.desc, 0, 8, TEXT_WIDTH, true))
+    end
+  end
+
+  if fun.attrs then
+    table.insert(ret, '\n    Attributes: ~\n')
+    for _, attr in ipairs(fun.attrs) do
+      local attr_str = ({
+        textlock = 'not allowed when |textlock| is active or in the |cmdwin|',
+        textlock_allow_cmdwin = 'not allowed when |textlock| is active',
+        fast = '|api-fast|',
+        remote_only = '|RPC| only',
+        lua_only = 'Lua |vim.api| only',
+      })[attr] or attr
+      table.insert(ret, fmt('        %s\n', attr_str))
+    end
+  end
+
+  if fun.params and #fun.params > 0 then
+    local param_txt = render_fields_or_params(fun.params, fun.generics, cfg.exclude_types)
+    if not param_txt:match('^%s*$') then
+      table.insert(ret, '\n    Parameters: ~\n')
+      ret[#ret + 1] = param_txt
+    end
+  end
+
+  if fun.returns then
+    local txt = render_returns(fun.returns, fun.generics, cfg.exclude_types)
+    if not txt:match('^%s*$') then