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.

runtime/doc/lsp.txt

@@ -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()|

runtime/doc/lua.txt

@@ -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}
+        (`string|integer[][]?`) See {opts.result_type}. `nil` if
-        is given.
+        {opts.on_hunk} is given.
 
 
 ==============================================================================

runtime/lua/vim/_meta/builtin.lua

@@ -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-32 index
---- @return integer UTF-16 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

runtime/lua/vim/lsp/rpc.lua

@@ -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()

scripts/luacats_grammar.lua

@@ -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'))
+--- @param x string | vim.lpeg.Pattern
-
-local lname = (ident + P('...')) * opt(P('?'))
-
---- @param x string
 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('cast', ty_name * ws * opt(Sf('+-')) * v.ctype)
-    + annot('generic', cname * opt(colon * v.ctype))
+    + annot('generic', ty_name * opt(colon * v.ctype))
-    + annot('class', opt_exact * opt(paren(caccess)) * fill * cname * opt_parent)
+    + 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('alias', ty_name * opt(ws * v.ctype))
-    + annot('enum', cname)
+    + 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'),
-
+  ty_index = C(Pf('[') * typedef * fill * P(']')),
-  ctype = parenOpt(Cg(v.ltype, 'type')),
+  ctype = Cg(typedef, '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(']'),
 }
 
 return grammar --[[@as nvim.luacats.grammar]]

test/functional/script/luacats_grammar_spec.lua

@@ -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)