mirror of
https://github.com/neovim/neovim.git
synced 2025-11-04 01:34:25 +00:00
9beb40a4db
Problem: The documentation flow (`gen_vimdoc.py`) has several issues: - it's not very versatile - depends on doxygen - doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C. - The intermediate XML files and filters makes it too much like a rube goldberg machine. Solution: Re-implement the flow using Lua, LPEG and treesitter. - `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic. - `lua2dox.lua` is gone! - No more XML files. - Doxygen is now longer used and instead we now use: - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`). - LPEG for C parsing (see `scripts/cdoc_parser.lua`) - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`). - Treesitter for Markdown parsing (see `scripts/text_utils.lua`). - The generated `runtime/doc/*.mpack` files have been removed. - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly. - Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
88 lines
1.9 KiB
Lua
88 lines
1.9 KiB
Lua
--[[!
|
|
LPEG grammar for C doc comments
|
|
]]
|
|
|
|
--- @class nvim.cdoc.Param
|
|
--- @field kind 'param'
|
|
--- @field name string
|
|
--- @field desc? string
|
|
|
|
--- @class nvim.cdoc.Return
|
|
--- @field kind 'return'
|
|
--- @field desc string
|
|
|
|
--- @class nvim.cdoc.Note
|
|
--- @field desc? string
|
|
|
|
--- @alias nvim.cdoc.grammar.result
|
|
--- | nvim.cdoc.Param
|
|
--- | nvim.cdoc.Return
|
|
--- | nvim.cdoc.Note
|
|
|
|
--- @class nvim.cdoc.grammar
|
|
--- @field match fun(self, input: string): nvim.cdoc.grammar.result?
|
|
|
|
local lpeg = vim.lpeg
|
|
local P, R, S = lpeg.P, lpeg.R, lpeg.S
|
|
local Ct, Cg = lpeg.Ct, lpeg.Cg
|
|
|
|
--- @param x vim.lpeg.Pattern
|
|
local function rep(x)
|
|
return x ^ 0
|
|
end
|
|
|
|
--- @param x vim.lpeg.Pattern
|
|
local function rep1(x)
|
|
return x ^ 1
|
|
end
|
|
|
|
--- @param x vim.lpeg.Pattern
|
|
local function opt(x)
|
|
return x ^ -1
|
|
end
|
|
|
|
local nl = P('\r\n') + P('\n')
|
|
local ws = rep1(S(' \t') + nl)
|
|
|
|
local any = P(1) -- (consume one character)
|
|
local letter = R('az', 'AZ') + S('_$')
|
|
local ident = letter * rep(letter + R('09'))
|
|
|
|
local io = P('[') * (P('in') + P('out') + P('inout')) * P(']')
|
|
|
|
--- @param x string
|
|
local function Pf(x)
|
|
return opt(ws) * P(x) * opt(ws)
|
|
end
|
|
|
|
--- @type table<string,vim.lpeg.Pattern>
|
|
local v = setmetatable({}, {
|
|
__index = function(_, k)
|
|
return lpeg.V(k)
|
|
end,
|
|
})
|
|
|
|
local grammar = P {
|
|
rep1(P('@') * v.ats),
|
|
|
|
ats = v.at_param + v.at_return + v.at_deprecated + v.at_see + v.at_brief + v.at_note + v.at_nodoc,
|
|
|
|
at_param = Ct(
|
|
Cg(P('param'), 'kind') * opt(io) * ws * Cg(ident, 'name') * opt(ws * Cg(rep(any), 'desc'))
|
|
),
|
|
|
|
at_return = Ct(Cg(P('return'), 'kind') * opt(S('s')) * opt(ws * Cg(rep(any), 'desc'))),
|
|
|
|
at_deprecated = Ct(Cg(P('deprecated'), 'kind')),
|
|
|
|
at_see = Ct(Cg(P('see'), 'kind') * ws * opt(Pf('#')) * Cg(rep(any), 'desc')),
|
|
|
|
at_brief = Ct(Cg(P('brief'), 'kind') * ws * Cg(rep(any), 'desc')),
|
|
|
|
at_note = Ct(Cg(P('note'), 'kind') * ws * Cg(rep(any), 'desc')),
|
|
|
|
at_nodoc = Ct(Cg(P('nodoc'), 'kind')),
|
|
}
|
|
|
|
return grammar --[[@as nvim.cdoc.grammar]]
|