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

@@ -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)
+    write(util.prefix_lines('--- ', norm_text(desc)))
-    for _, l in ipairs(split(norm_text(desc))) do
-      write('--- ' .. l)
-    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
+    write(util.prefix_lines('--- ', table.concat(fun.notes, '\n')))
-      -- 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('---')
   end
 
   for _, see in ipairs(fun.see or {}) do
-    see = util.md_to_vimdoc('@see ' .. see, 0, 0, 74)
+    write(util.prefix_lines('--- @see ', norm_text(see)))
-    for _, l in ipairs(split(vim.trim(norm_text(see)))) do
-      write('--- ' .. l:gsub([[\s*$]], ''))
-    end
   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, ', ')
 

scripts/util.lua

@@ -175,15 +175,16 @@ end
 
 --- Prefixes each line in `text`.
 ---
---- Does not wrap, that's not important for "meta" files? (You probably want md_to_vimdoc instead.)
+--- Does not wrap, not important for "meta" files? (You probably want md_to_vimdoc instead.)
 ---
 --- @param text string
 --- @param prefix_ string
-function M.prefix(prefix_, text)
+function M.prefix_lines(prefix_, text)
-  if (text):find('\n$') then
+  local r = ''
-    return text:gsub('([^\n]*)[\t ]*\n', prefix_ .. '%1\n')
+  for _, l in ipairs(vim.split(text, '\n', { plain = true })) do
+    r = r .. vim.trim(prefix_ .. l) .. '\n'
   end
-  return prefix_ .. text:gsub('([^\n]*)[\t ]*\n', '%1\n' .. prefix_)
+  return r
 end
 
 --- @param x string