mirror of
https://github.com/neovim/neovim.git
synced 2024-12-24 05:05:00 -07:00
docs: improve luacats support #30580
Some composite/compound types even as basic as `(string|number)[]` are not currently supported by the luacats LPEG grammar used by gen_vimdoc. It would be parsed & rendered as just `string|number`. Changeset adds better support for these types.
This commit is contained in:
James Trew
GitHub
parent
c6abc97006
commit
385fbfb3e7
@ -2303,7 +2303,7 @@ Lua module: vim.lsp.rpc *lsp-rpc*
|
||||
*vim.lsp.rpc.PublicClient*
|
||||
|
||||
Fields: ~
|
||||
• {request} (`fun(method: string, params: table?, callback: fun(err: lsp.ResponseError?, result: any), notify_reply_callback: fun(integer)?):boolean,integer?`)
|
||||
• {request} (`fun(method: string, params: table?, callback: fun(err: lsp.ResponseError?, result: any), notify_reply_callback: fun(message_id: integer)?):boolean,integer?`)
|
||||
see |vim.lsp.rpc.request()|
|
||||
• {notify} (`fun(method: string, params: any):boolean`) see
|
||||
|vim.lsp.rpc.notify()|
|
||||
|
||||
@ -752,8 +752,8 @@ vim.diff({a}, {b}, {opts}) *vim.diff()*
|
||||
the internal diff library.
|
||||
|
||||
Return: ~
|
||||
(`string|integer[]`) See {opts.result_type}. `nil` if {opts.on_hunk}
|
||||
is given.
|
||||
(`string|integer[][]?`) See {opts.result_type}. `nil` if
|
||||
{opts.on_hunk} is given.
|
||||
|
||||
|
||||
==============================================================================
|
||||
|
||||
@ -182,8 +182,8 @@ function vim.str_utf_end(str, index) end
|
||||
--- that sequence.
|
||||
--- @param str string
|
||||
--- @param index? integer
|
||||
--- @return integer UTF-32 index
|
||||
--- @return integer UTF-16 index
|
||||
--- @return integer # UTF-32 index
|
||||
--- @return integer # UTF-16 index
|
||||
function vim.str_utfindex(str, index) end
|
||||
|
||||
--- The result is a String, which is the text {str} converted from
|
||||
|
||||
@ -550,7 +550,7 @@ local function new_client(dispatchers, transport)
|
||||
end
|
||||
|
||||
---@class vim.lsp.rpc.PublicClient
|
||||
---@field request fun(method: string, params: table?, callback: fun(err: lsp.ResponseError|nil, result: any), notify_reply_callback: fun(integer)|nil):boolean,integer? see |vim.lsp.rpc.request()|
|
||||
---@field request fun(method: string, params: table?, callback: fun(err: lsp.ResponseError|nil, result: any), notify_reply_callback: fun(message_id: integer)|nil):boolean,integer? see |vim.lsp.rpc.request()|
|
||||
---@field notify fun(method: string, params: any):boolean see |vim.lsp.rpc.notify()|
|
||||
---@field is_closing fun(): boolean
|
||||
---@field terminate fun()
|
||||
|
||||
@ -4,7 +4,7 @@ LPEG grammar for LuaCATS
|
||||
|
||||
local lpeg = vim.lpeg
|
||||
local P, R, S = lpeg.P, lpeg.R, lpeg.S
|
||||
local Ct, Cg = lpeg.Ct, lpeg.Cg
|
||||
local C, Ct, Cg = lpeg.C, lpeg.Ct, lpeg.Cg
|
||||
|
||||
--- @param x vim.lpeg.Pattern
|
||||
local function rep(x)
|
||||
@ -23,23 +23,20 @@ end
|
||||
|
||||
local ws = rep1(S(' \t'))
|
||||
local fill = opt(ws)
|
||||
|
||||
local any = P(1) -- (consume one character)
|
||||
local letter = R('az', 'AZ') + S('_$')
|
||||
local letter = R('az', 'AZ')
|
||||
local num = R('09')
|
||||
local ident = letter * rep(letter + num + S '-.')
|
||||
local string_single = P "'" * rep(any - P "'") * P "'"
|
||||
local string_double = P('"') * rep(any - P('"')) * P('"')
|
||||
|
||||
local literal = (string_single + string_double + (opt(P('-')) * num) + P('false') + P('true'))
|
||||
|
||||
local lname = (ident + P('...')) * opt(P('?'))
|
||||
|
||||
--- @param x string
|
||||
--- @param x string | vim.lpeg.Pattern
|
||||
local function Pf(x)
|
||||
return fill * P(x) * fill
|
||||
end
|
||||
|
||||
--- @param x string | vim.lpeg.Pattern
|
||||
local function Plf(x)
|
||||
return fill * P(x)
|
||||
end
|
||||
|
||||
--- @param x string
|
||||
local function Sf(x)
|
||||
return fill * S(x) * fill
|
||||
@ -72,16 +69,6 @@ local v = setmetatable({}, {
|
||||
end,
|
||||
})
|
||||
|
||||
local colon = Pf(':')
|
||||
local opt_exact = opt(Cg(Pf('(exact)'), 'access'))
|
||||
local access = P('private') + P('protected') + P('package')
|
||||
local caccess = Cg(access, 'access')
|
||||
local desc_delim = Sf '#:' + ws
|
||||
local desc = Cg(rep(any), 'desc')
|
||||
local opt_desc = opt(desc_delim * desc)
|
||||
local cname = Cg(ident, 'name')
|
||||
local opt_parent = opt(colon * Cg(ident, 'parent'))
|
||||
|
||||
--- @class nvim.luacats.Param
|
||||
--- @field kind 'param'
|
||||
--- @field name string
|
||||
@ -135,21 +122,69 @@ local function annot(nm, pat)
|
||||
return Ct(Cg(P(nm), 'kind'))
|
||||
end
|
||||
|
||||
local colon = Pf(':')
|
||||
local ellipsis = P('...')
|
||||
local ident_first = P('_') + letter
|
||||
local ident = ident_first * rep(ident_first + num)
|
||||
local opt_ident = ident * opt(P('?'))
|
||||
local ty_ident_sep = S('-._')
|
||||
local ty_ident = ident * rep(ty_ident_sep * ident)
|
||||
local string_single = P "'" * rep(any - P "'") * P "'"
|
||||
local string_double = P('"') * rep(any - P('"')) * P('"')
|
||||
local generic = P('`') * ty_ident * P('`')
|
||||
local literal = string_single + string_double + (opt(P('-')) * rep1(num)) + P('false') + P('true')
|
||||
local ty_prims = ty_ident + literal + generic
|
||||
|
||||
local array_postfix = rep1(Plf('[]'))
|
||||
local opt_postfix = rep1(Plf('?'))
|
||||
local rep_array_opt_postfix = rep(array_postfix + opt_postfix)
|
||||
|
||||
local typedef = P({
|
||||
'typedef',
|
||||
typedef = C(v.type),
|
||||
|
||||
type = v.ty * rep_array_opt_postfix * rep(Pf('|') * v.ty * rep_array_opt_postfix),
|
||||
ty = v.composite + paren(v.typedef),
|
||||
composite = (v.types * array_postfix) + (v.types * opt_postfix) + v.types,
|
||||
types = v.generics + v.kv_table + v.tuple + v.dict + v.table_literal + v.fun + ty_prims,
|
||||
|
||||
tuple = Pf('[') * comma1(v.type) * Plf(']'),
|
||||
dict = Pf('{') * comma1(Pf('[') * v.type * Pf(']') * colon * v.type) * Plf('}'),
|
||||
kv_table = Pf('table') * Pf('<') * v.type * Pf(',') * v.type * Plf('>'),
|
||||
table_literal = Pf('{') * comma1(opt_ident * Pf(':') * v.type) * Plf('}'),
|
||||
fun_param = (opt_ident + ellipsis) * opt(colon * v.type),
|
||||
fun_ret = v.type + (ellipsis * opt(colon * v.type)),
|
||||
fun = Pf('fun') * paren(comma(v.fun_param)) * opt(Pf(':') * comma1(v.fun_ret)),
|
||||
generics = P(ty_ident) * Pf('<') * comma1(v.type) * Plf('>'),
|
||||
}) / function(match)
|
||||
return vim.trim(match):gsub('^%((.*)%)$', '%1'):gsub('%?+', '?')
|
||||
end
|
||||
|
||||
local opt_exact = opt(Cg(Pf('(exact)'), 'access'))
|
||||
local access = P('private') + P('protected') + P('package')
|
||||
local caccess = Cg(access, 'access')
|
||||
local desc_delim = Sf '#:' + ws
|
||||
local desc = Cg(rep(any), 'desc')
|
||||
local opt_desc = opt(desc_delim * desc)
|
||||
local ty_name = Cg(ty_ident, 'name')
|
||||
local opt_parent = opt(colon * Cg(ty_ident, 'parent'))
|
||||
local lname = (ident + ellipsis) * opt(P('?'))
|
||||
|
||||
local grammar = P {
|
||||
rep1(P('@') * (v.ats + v.ext_ats)),
|
||||
|
||||
ats = annot('param', Cg(lname, 'name') * ws * v.ctype * opt_desc)
|
||||
+ annot('return', comma1(Ct(v.ctype * opt(ws * cname))) * opt_desc)
|
||||
+ annot('return', comma1(Ct(v.ctype * opt(ws * (ty_name + Cg(ellipsis, 'name'))))) * opt_desc)
|
||||
+ annot('type', comma1(Ct(v.ctype)) * opt_desc)
|
||||
+ annot('cast', cname * ws * opt(Sf('+-')) * v.ctype)
|
||||
+ annot('generic', cname * opt(colon * v.ctype))
|
||||
+ annot('class', opt_exact * opt(paren(caccess)) * fill * cname * opt_parent)
|
||||
+ annot('cast', ty_name * ws * opt(Sf('+-')) * v.ctype)
|
||||
+ annot('generic', ty_name * opt(colon * v.ctype))
|
||||
+ annot('class', opt_exact * opt(paren(caccess)) * fill * ty_name * opt_parent)
|
||||
+ annot('field', opt(caccess * ws) * v.field_name * ws * v.ctype * opt_desc)
|
||||
+ annot('operator', cname * opt(paren(Cg(v.ltype, 'argtype'))) * colon * v.ctype)
|
||||
+ annot('operator', ty_name * opt(paren(Cg(v.ctype, 'argtype'))) * colon * v.ctype)
|
||||
+ annot(access)
|
||||
+ annot('deprecated')
|
||||
+ annot('alias', cname * opt(ws * v.ctype))
|
||||
+ annot('enum', cname)
|
||||
+ annot('alias', ty_name * opt(ws * v.ctype))
|
||||
+ annot('enum', ty_name)
|
||||
+ annot('overload', v.ctype)
|
||||
+ annot('see', opt(desc_delim) * desc)
|
||||
+ annot('diagnostic', opt(desc_delim) * desc)
|
||||
@ -165,23 +200,8 @@ local grammar = P {
|
||||
),
|
||||
|
||||
field_name = Cg(lname + (v.ty_index * opt(P('?'))), 'name'),
|
||||
|
||||
ctype = parenOpt(Cg(v.ltype, 'type')),
|
||||
ltype = parenOpt(v.ty_union),
|
||||
|
||||
ty_union = v.ty_opt * rep(Pf('|') * v.ty_opt),
|
||||
ty = v.ty_fun + ident + v.ty_table + literal + paren(v.ty) + v.ty_generic + v.ty_tuple,
|
||||
ty_param = Pf('<') * comma1(v.ltype) * fill * P('>'),
|
||||
ty_opt = v.ty * opt(v.ty_param) * opt(P('[]')) * opt(P('?')),
|
||||
ty_index = (Pf('[') * (v.ltype + ident + rep1(num)) * fill * P(']')),
|
||||
table_key = v.ty_index + lname,
|
||||
table_elem = v.table_key * colon * v.ltype,
|
||||
ty_table = Pf('{') * comma1(v.table_elem) * fill * P('}'),
|
||||
fun_param = lname * opt(colon * v.ltype),
|
||||
fun_ret = v.ltype + (ident * colon * v.ltype) + (P('...') * opt(colon * v.ltype)),
|
||||
ty_fun = Pf('fun') * paren(comma(lname * opt(colon * v.ltype))) * opt(colon * comma1(v.fun_ret)),
|
||||
ty_generic = P('`') * letter * P('`'),
|
||||
ty_tuple = Pf('[') * comma(v.ltype) * fill * P(']'),
|
||||
ty_index = C(Pf('[') * typedef * fill * P(']')),
|
||||
ctype = Cg(typedef, 'type'),
|
||||
}
|
||||
|
||||
return grammar --[[@as nvim.luacats.grammar]]
|
||||
|
||||
@ -166,4 +166,122 @@ describe('luacats grammar', function()
|
||||
name = 'type',
|
||||
type = '[number,string,"good"|"bad"]',
|
||||
})
|
||||
|
||||
test('@class vim.diagnostic.JumpOpts', {
|
||||
kind = 'class',
|
||||
name = 'vim.diagnostic.JumpOpts',
|
||||
})
|
||||
|
||||
test('@class vim.diagnostic.JumpOpts : vim.diagnostic.GetOpts', {
|
||||
kind = 'class',
|
||||
name = 'vim.diagnostic.JumpOpts',
|
||||
parent = 'vim.diagnostic.GetOpts',
|
||||
})
|
||||
|
||||
test('@param opt? { cmd?: string[] } Options', {
|
||||
kind = 'param',
|
||||
name = 'opt?',
|
||||
type = '{ cmd?: string[] }',
|
||||
desc = 'Options',
|
||||
})
|
||||
|
||||
---@type [string, string?][]
|
||||
local test_cases = {
|
||||
{ 'foo' },
|
||||
{ 'foo ', 'foo' }, -- trims whitespace
|
||||
{ 'true' },
|
||||
{ 'vim.type' },
|
||||
{ 'vim-type' },
|
||||
{ 'vim_type' },
|
||||
{ 'foo.bar-baz_baz' },
|
||||
{ '`ABC`' },
|
||||
{ '42' },
|
||||
{ '-42' },
|
||||
{ '(foo)', 'foo' }, -- removes unnecessary parens
|
||||
{ 'true?' },
|
||||
{ '(true)?' },
|
||||
{ 'string[]' },
|
||||
{ 'string|number' },
|
||||
{ '(string)[]' },
|
||||
{ '(string|number)[]' },
|
||||
{ 'coalesce??', 'coalesce?' }, -- removes unnecessary ?
|
||||
{ 'number?|string' },
|
||||
{ "'foo'|'bar'|'baz'" },
|
||||
{ '"foo"|"bar"|"baz"' },
|
||||
{ '(number)?|string' }, --
|
||||
{ 'number[]|string' },
|
||||
{ 'string[]?' },
|
||||
{ 'foo?[]' },
|
||||
{ 'vim.type?|string? ', 'vim.type?|string?' },
|
||||
{ 'number[][]' },
|
||||
{ 'number[][][]' },
|
||||
{ 'number[][]?' },
|
||||
{ 'string|integer[][]?' },
|
||||
|
||||
-- tuples
|
||||
{ '[string]' },
|
||||
{ '[1]' },
|
||||
{ '[string, number]' },
|
||||
{ '[string, number]?' },
|
||||
{ '[string, number][]' },
|
||||
{ '[string, number]|string' },
|
||||
{ '[string|number, number?]' },
|
||||
{ 'string|[string, number]' },
|
||||
{ '(true)?|[foo]' },
|
||||
{ '[fun(a: string):boolean]' },
|
||||
|
||||
-- dict
|
||||
{ '{[string]:string}' },
|
||||
{ '{ [ string ] : string }' },
|
||||
{ '{ [ string|any ] : string }' },
|
||||
{ '{[string]: string, [number]: boolean}' },
|
||||
|
||||
-- key-value table
|
||||
{ 'table<string,any>' },
|
||||
{ 'table' },
|
||||
{ 'string|table|boolean' },
|
||||
{ 'string|table|(boolean)' },
|
||||
|
||||
-- table literal
|
||||
{ '{foo: number}' },
|
||||
{ '{foo: string, bar: [number, boolean]?}' },
|
||||
{ 'boolean|{reverse?:boolean}' },
|
||||
{ '{ cmd?: string[] }' },
|
||||
|
||||
-- function
|
||||
{ 'fun(a: string, b:foo|bar): string' },
|
||||
{ 'fun(a?: string): string' },
|
||||
{ 'fun(a?: string): number?,string?' },
|
||||
{ '(fun(a: string, b:foo|bar): string)?' },
|
||||
{ 'fun(a: string, b:foo|bar): string, string' },
|
||||
{ 'fun(a: string, b:foo|bar)' },
|
||||
{ 'fun(_, foo, bar): string' },
|
||||
{ 'fun(...): number' },
|
||||
{ 'fun( ... ): number' },
|
||||
{ 'fun(...:number): number' },
|
||||
{ 'fun( ... : number): number' },
|
||||
|
||||
-- generics
|
||||
{ 'elem_or_list<string>' },
|
||||
{
|
||||
'elem_or_list<fun(client: vim.lsp.Client, initialize_result: lsp.InitializeResult)>',
|
||||
nil,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tc in ipairs(test_cases) do
|
||||
local ty, exp_ty = tc[1], tc[2]
|
||||
if exp_ty == nil then
|
||||
exp_ty = ty
|
||||
end
|
||||
|
||||
local var, desc = 'x', 'some desc'
|
||||
local param = string.format('@param %s %s %s', var, ty, desc)
|
||||
test(param, {
|
||||
kind = 'param',
|
||||
name = var,
|
||||
type = exp_ty,
|
||||
desc = desc,
|
||||
})
|
||||
end
|
||||
end)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user