From a7df0415ab6ae9a89ca12c6765758bfd54fa69c9 Mon Sep 17 00:00:00 2001
From: Jongwook Choi <wookayin@gmail.com>
Date: Sat, 13 Jan 2024 18:36:30 -0500
Subject: [PATCH] fix(lua2dox): filter out the entire `---@alias` block

Problem: Any preceding luadocs block that define alias types with
`@alias` magic would be prepended to the documentation of functions
that follow, despite the "blank line" separator. For example:

```
--- @alias some.type.between.functions
--- Blah blah long documentation for alias
--- | "foo" # foo
--- | "bar" # bar

--- The documentation that should appear in vimdoc.
function M.function_to_include_in_doc()
  ...
end
```

then the vimdoc generated for `function_to_include_in_doc` would include
the text from the alias block (e.g., "Blah blah ... for alias").

Solution:

- refactor: Lua2DoxFilter should maintain its own internal state
  `generics`, rather than carrying it as a parameter to local helper
  functions.

- Add another boolean state `boolean_state` which represents whether
  to ignore the current docstring block (magic lines). This flag will
  be reset as soon as the block is end.

Note: As expected, there is no change at all in the current docs
generated, because we have been working around and writing luadoc
comments so that such erroneous docstring resulting from preceding
`@alias` blocks won't appear.
---
 scripts/lua2dox.lua | 48 +++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 17 deletions(-)

diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index abc9e5b338..871720bd2a 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -136,9 +136,17 @@ end
 
 -- input filter
 --- @class Lua2DoxFilter
-local Lua2DoxFilter = {}
+local Lua2DoxFilter = {
+  generics = {}, --- @type table<string,string>
+  block_ignore = false, --- @type boolean
+}
 setmetatable(Lua2DoxFilter, { __index = Lua2DoxFilter })
 
+function Lua2DoxFilter:reset()
+  self.generics = {}
+  self.block_ignore = false
+end
+
 --- trim comment off end of string
 ---
 --- @param line string
@@ -239,13 +247,16 @@ end
 --- Processes "@…" directives in a docstring line.
 ---
 --- @param line string
---- @param generics table<string,string>
 --- @return string?
-local function process_magic(line, generics)
+function Lua2DoxFilter:process_magic(line)
   line = line:gsub('^%s+@', '@')
   line = line:gsub('@package', '@private')
   line = line:gsub('@nodoc', '@private')
 
+  if self.block_ignore then
+    return '// gg:" ' .. line .. '"'
+  end
+
   if not vim.startswith(line, '@') then -- it's a magic comment
     return '/// ' .. line
   end
@@ -269,6 +280,12 @@ local function process_magic(line, generics)
     return '/// ' .. line:gsub('%.', '-dot-')
   end
 
+  if directive == '@alias' then
+    -- this contiguous block should be all ignored.
+    self.block_ignore = true
+    return '// gg:"' .. line .. '"'
+  end
+
   -- preprocess line before parsing
   if directive == '@param' or directive == '@return' then
     for _, type in ipairs(TYPES) do
@@ -289,12 +306,12 @@ local function process_magic(line, generics)
   local kind = parsed.kind
 
   if kind == 'generic' then
-    generics[parsed.name] = parsed.type or 'any'
+    self.generics[parsed.name] = parsed.type or 'any'
     return
   elseif kind == 'param' then
-    return process_param(parsed --[[@as luacats.Param]], generics)
+    return process_param(parsed --[[@as luacats.Param]], self.generics)
   elseif kind == 'return' then
-    return process_return(parsed --[[@as luacats.Return]], generics)
+    return process_return(parsed --[[@as luacats.Return]], self.generics)
   end
 
   error(string.format('unhandled parsed line %q: %s', line, parsed))
@@ -303,7 +320,7 @@ end
 --- @param line string
 --- @param in_stream StreamRead
 --- @return string
-local function process_block_comment(line, in_stream)
+function Lua2DoxFilter:process_block_comment(line, in_stream)
   local comment_parts = {} --- @type string[]
   local done --- @type boolean?
 
@@ -337,7 +354,7 @@ end
 
 --- @param line string
 --- @return string
-local function process_function_header(line)
+function Lua2DoxFilter:process_function_header(line)
   local pos_fn = assert(line:find('function'))
   -- we've got a function
   local fn = removeCommentFromLine(vim.trim(line:sub(pos_fn + 8)))
@@ -385,18 +402,17 @@ end
 
 --- @param line string
 --- @param in_stream StreamRead
---- @param generics table<string,string>>
 --- @return string?
-local function process_line(line, in_stream, generics)
+function Lua2DoxFilter:process_line(line, in_stream)
   local line_raw = line
   line = vim.trim(line)
 
   if vim.startswith(line, '---') then
-    return process_magic(line:sub(4), generics)
+    return Lua2DoxFilter:process_magic(line:sub(4))
   end
 
   if vim.startswith(line, '--' .. '[[') then -- it's a long comment
-    return process_block_comment(line:sub(5), in_stream)
+    return Lua2DoxFilter:process_block_comment(line:sub(5), in_stream)
   end
 
   -- Hax... I'm sorry
@@ -406,7 +422,7 @@ local function process_line(line, in_stream, generics)
   line = line:gsub('^(.+) = .*_memoize%([^,]+, function%((.*)%)$', 'function %1(%2)')
 
   if line:find('^function') or line:find('^local%s+function') then
-    return process_function_header(line)
+    return Lua2DoxFilter:process_function_header(line)
   end
 
   if not line:match('^local') then
@@ -429,15 +445,13 @@ end
 function Lua2DoxFilter:filter(filename)
   local in_stream = StreamRead.new(filename)
 
-  local generics = {} --- @type table<string,string>
-
   while not in_stream:eof() do
     local line = in_stream:getLine()
 
-    local out_line = process_line(line, in_stream, generics)
+    local out_line = self:process_line(line, in_stream)
 
     if not vim.startswith(vim.trim(line), '---') then
-      generics = {}
+      self:reset()
     end
 
     if out_line then