fix(doc): prevent doxygen confusion

2 files changed, 14 insertions, 2 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index bf0408c773..bee0445e4e 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -742,14 +742,14 @@ open_float({opts}, {...})                        *vim.diagnostic.open_float()*
         (`integer?, integer?`) ({float_bufnr}, {win_id})
 
 reset({namespace}, {bufnr})                           *vim.diagnostic.reset()*
+    Remove all diagnostics from the given namespace.
+
     Unlike |vim.diagnostic.hide()|, this function removes all saved
     diagnostics. They cannot be redisplayed using |vim.diagnostic.show()|. To
     simply remove diagnostic decorations in a way that they can be
     re-displayed, use |vim.diagnostic.hide()|.
 
     Parameters: ~
-      • {d}          (`vim.Diagnostic`) Remove all diagnostics from the given
-             namespace.
       • {namespace}  (`integer?`) Diagnostic namespace. When omitted, remove
                      diagnostics from all namespaces.
       • {bufnr}      (`integer?`) Remove diagnostics for the given buffer.
diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index 4f9973449e..0b3daa59b2 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -447,6 +447,8 @@ end
 function Lua2DoxFilter:filter(filename)
   local in_stream = StreamRead.new(filename)
 
+  local last_was_magic = false
+
   while not in_stream:eof() do
     local line = in_stream:getLine()
 
@@ -457,6 +459,16 @@ function Lua2DoxFilter:filter(filename)
     end
 
     if out_line then
+      -- Ensure all magic blocks associate with some object to prevent doxygen
+      -- from getting confused.
+      if vim.startswith(out_line, '///') then
+        last_was_magic = true
+      else
+        if last_was_magic and out_line:match('^// zz: [^-]+') then
+          writeln('local_function _ignore() {}')
+        end
+        last_was_magic = false
+      end
       writeln(out_line)
     end
   end