From 98f3d1dae2d857654ba4ded74a9974e6b3574439 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Sat, 26 Apr 2025 14:25:08 -0700
Subject: feat(docgen.lua): convert `@brief` codeblocks for vimdoc #3787

---
 lsp/jqls.lua       |  1 +
 lsp/uvls.lua       |  1 +
 scripts/docgen.lua | 37 +++++++++++++++++++++++++++++++++----
 3 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/lsp/jqls.lua b/lsp/jqls.lua
index e5cde7c6..d03230d1 100644
--- a/lsp/jqls.lua
+++ b/lsp/jqls.lua
@@ -8,6 +8,7 @@
 --- go install github.com/wader/jq-lsp@master
 --- # copy binary to $PATH
 --- cp $(go env GOPATH)/bin/jq-lsp /usr/local/bin
+---
 --- ```
 --- Note: To activate properly nvim needs to know the jq filetype.
 --- You can add it via:
diff --git a/lsp/uvls.lua b/lsp/uvls.lua
index 17bde9f2..7b78c09f 100644
--- a/lsp/uvls.lua
+++ b/lsp/uvls.lua
@@ -8,6 +8,7 @@
 --- cd  uvls
 --- cargo install --path .
 --- ```
+---
 --- Note: To activate properly nvim needs to know the uvl filetype.
 --- You can add it via:
 --- ```lua
diff --git a/scripts/docgen.lua b/scripts/docgen.lua
index af308363..28213cef 100755
--- a/scripts/docgen.lua
+++ b/scripts/docgen.lua
@@ -87,8 +87,32 @@ Default config:
 ---
 ]]
 
+--- Converts markdown "```" codeblock to vimdoc format.
+local function codeblock_to_vimdoc(doc)
+  local function make_fn(before, extra)
+    return function(lang, code)
+      if not code then
+        code = lang
+        lang = ''
+      end
+      -- Indent code by 2 spaces.
+      return before .. '>' .. lang .. extra .. code:gsub('[^\n]+', '  %0')
+    end
+  end
+
+  doc = doc
+    -- "```lang" following a nonblank line.
+    :gsub('[^%s]\n```(%w+)\n(.-)\n```', make_fn(' ', '\n'))
+    -- "```lang" following a blank line.
+    :gsub('\n```(%w+)\n(.-)\n```', make_fn('', '\n'))
+    -- "```" (no language)
+    :gsub('\n```\n(..-)\n```', make_fn('', '\n'))
+
+  return doc
+end
+
 --- Gets docstring by looking for "@brief" in a Lua code docstring.
-local function extract_brief(text)
+local function extract_brief(text, is_markdown)
   local doc = text:match('%-%-+ *%@brief.-(\n%-%-.*)')
   if not doc then
     return ''
@@ -99,12 +123,18 @@ local function extract_brief(text)
   doc = doc:gsub('\n%-%-+', '\n')
   -- Remove leading whitespace (shared indent).
   doc = vim.trim(vim.text.indent(0, doc))
+
+  -- Convert codeblocks for vimdoc.
+  if not is_markdown then
+    doc = codeblock_to_vimdoc(doc)
+  end
+
   return doc
 end
 
 local function make_lsp_section(config_sections, config_name, config_file, is_markdown)
   local config = require('lsp.' .. config_name)
-  local docstring = extract_brief(readfile(config_file))
+  local docstring = extract_brief(readfile(config_file), is_markdown)
   local params = {
     config_name = config_name,
     preamble = docstring,
@@ -186,8 +216,7 @@ local function make_lsp_sections(is_markdown)
       -- vim.env.HOME = '/home/user'
       -- vim.env.XDG_CACHE_HOME = '/home/user/.cache'
       local old_fn = vim.fn
-      local new_fn = {}
-      vim.fn = setmetatable(new_fn, {
+      vim.fn = setmetatable({}, {
         __index = function(_t, key)
           if key == 'getpid' then
             return function()
-- 
cgit v1.2.3-70-g09d2