mirror of
https://github.com/neovim/neovim.git
synced 2024-12-24 13:15:09 -07:00
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.
This commit is contained in:
parent
2cdea852e8
commit
a7df0415ab
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user