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.

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'))
-
-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]]