fix(doc): improve doc generation of types using lpeg

Added a lpeg grammar for LuaCATS and use it in lua2dox.lua

runtime/lua/vim/_editor.lua

@@ -95,7 +95,7 @@ vim.log = {
 --- throws an error if {cmd} cannot be run.
 ---
 --- @param cmd (string[]) Command to execute
---- @param opts (SystemOpts|nil) Options:
+--- @param opts vim.SystemOpts? Options:
 ---   - cwd: (string) Set the current working directory for the sub-process.
 ---   - env: table<string,string> Set environment variables for the new process. Inherits the
 ---     current environment with `NVIM` set to |v:servername|.
@@ -118,7 +118,7 @@ vim.log = {
 ---     parent exits. Note that the child process will still keep the parent's event loop alive
 ---     unless the parent process calls |uv.unref()| on the child's process handle.
 ---
---- @param on_exit (function|nil) Called when subprocess exits. When provided, the command runs
+--- @param on_exit? fun(out: vim.SystemCompleted) Called when subprocess exits. When provided, the command runs
 ---   asynchronously. Receives SystemCompleted object, see return of SystemObj:wait().
 ---
 --- @return vim.SystemObj Object with the fields:
@@ -219,10 +219,9 @@ do
   --- ```
   ---
   ---@see |paste|
-  ---@alias paste_phase -1 | 1 | 2 | 3
   ---
   ---@param lines  string[] # |readfile()|-style list of lines to paste. |channel-lines|
-  ---@param phase paste_phase  -1: "non-streaming" paste: the call contains all lines.
+  ---@param phase (-1|1|2|3)  -1: "non-streaming" paste: the call contains all lines.
   ---              If paste is "streamed", `phase` indicates the stream state:
   ---                - 1: starts the paste (exactly once)
   ---                - 2: continues the paste (zero or more times)

runtime/lua/vim/_meta/api.lua

@@ -812,9 +812,8 @@ function vim.api.nvim_complete_set(index, opts) end
 --- @return integer
 function vim.api.nvim_create_augroup(name, opts) end
 
---- Creates an `autocommand` event handler, defined by `callback` (Lua
---- function or Vimscript function name string) or `command` (Ex command
---- string).
+--- Creates an `autocommand` event handler, defined by `callback` (Lua function
+--- or Vimscript function name string) or `command` (Ex command string).
 --- Example using Lua callback:
 ---
 --- ```lua

runtime/lua/vim/_system.lua

@@ -1,6 +1,6 @@
 local uv = vim.uv
 
---- @class SystemOpts
+--- @class vim.SystemOpts
 --- @field stdin? string|string[]|true
 --- @field stdout? fun(err:string?, data: string?)|false
 --- @field stderr? fun(err:string?, data: string?)|false
@@ -302,7 +302,7 @@ end
 --- Run a system command
 ---
 --- @param cmd string[]
---- @param opts? SystemOpts
+--- @param opts? vim.SystemOpts
 --- @param on_exit? fun(out: vim.SystemCompleted)
 --- @return vim.SystemObj
 function M.run(cmd, opts, on_exit)

runtime/lua/vim/filetype.lua

@@ -2165,7 +2165,7 @@ end
 --- }
 --- ```
 ---
----@param filetypes vim.filetype.add.filetypes A table containing new filetype maps (see example).
+---@param filetypes vim.filetype.add.filetypes (table) A table containing new filetype maps (see example).
 function M.add(filetypes)
   for k, v in pairs(filetypes.extension or {}) do
     extension[k] = v
@@ -2300,7 +2300,7 @@ end
 --- vim.filetype.match({ contents = {'#!/usr/bin/env bash'} })
 --- ```
 ---
----@param args vim.filetype.match.args Table specifying which matching strategy to use.
+---@param args vim.filetype.match.args (table) Table specifying which matching strategy to use.
 ---                 Accepted keys are:
 ---                   * buf (number): Buffer number to use for matching. Mutually exclusive with
 ---                                   {contents}

runtime/lua/vim/health.lua

@@ -315,7 +315,7 @@ end
 --- Run a system command and timeout after 30 seconds.
 ---
 --- @param cmd table List of command arguments to execute
---- @param args ?table Optional arguments:
+--- @param args? table Optional arguments:
 ---                   - stdin (string): Data to write to the job's stdin
 ---                   - stderr (boolean): Append stderr to stdout
 ---                   - ignore_error (boolean): If true, ignore error output

runtime/lua/vim/iter.lua

@@ -181,9 +181,9 @@ end
 --- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
 --- ```
 ---
----@param f function(...):bool Takes all values returned from the previous stage
----                            in the pipeline and returns false or nil if the
----                            current iterator element should be removed.
+---@param f fun(...):bool Takes all values returned from the previous stage
+---                       in the pipeline and returns false or nil if the
+---                       current iterator element should be removed.
 ---@return Iter
 function Iter.filter(self, f)
   return self:map(function(...)
@@ -272,11 +272,11 @@ end
 --- -- { 6, 12 }
 --- ```
 ---
----@param f function(...):any Mapping function. Takes all values returned from
----                           the previous stage in the pipeline as arguments
----                           and returns one or more new values, which are used
----                           in the next pipeline stage. Nil return values
----                           are filtered from the output.
+---@param f fun(...):any Mapping function. Takes all values returned from
+---                      the previous stage in the pipeline as arguments
+---                      and returns one or more new values, which are used
+---                      in the next pipeline stage. Nil return values
+---                      are filtered from the output.
 ---@return Iter
 function Iter.map(self, f)
   -- Implementation note: the reader may be forgiven for observing that this
@@ -340,9 +340,9 @@ end
 ---
 --- For functions with side effects. To modify the values in the iterator, use |Iter:map()|.
 ---
----@param f function(...) Function to execute for each item in the pipeline.
----                       Takes all of the values returned by the previous stage
----                       in the pipeline as arguments.
+---@param f fun(...) Function to execute for each item in the pipeline.
+---                  Takes all of the values returned by the previous stage
+---                  in the pipeline as arguments.
 function Iter.each(self, f)
   local function fn(...)
     if select(1, ...) ~= nil then
@@ -464,7 +464,7 @@ end
 ---@generic A
 ---
 ---@param init A Initial value of the accumulator.
----@param f function(acc:A, ...):A Accumulation function.
+---@param f fun(acc:A, ...):A Accumulation function.
 ---@return A
 function Iter.fold(self, init, f)
   local acc = init
@@ -884,9 +884,9 @@ end
 
 --- Returns true if any of the items in the iterator match the given predicate.
 ---
----@param pred function(...):bool Predicate function. Takes all values returned from the previous
----                                stage in the pipeline as arguments and returns true if the
----                                predicate matches.
+---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+---                          stage in the pipeline as arguments and returns true if the
+---                          predicate matches.
 function Iter.any(self, pred)
   local any = false
 
@@ -908,9 +908,9 @@ end
 
 --- Returns true if all items in the iterator match the given predicate.
 ---
----@param pred function(...):bool Predicate function. Takes all values returned from the previous
----                                stage in the pipeline as arguments and returns true if the
----                                predicate matches.
+---@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+---                          stage in the pipeline as arguments and returns true if the
+---                          predicate matches.
 function Iter.all(self, pred)
   local all = true
 
@@ -1106,9 +1106,9 @@ end
 ---
 ---@see |Iter:filter()|
 ---
----@param f function(...):bool Filter function. Accepts the current iterator or table values as
----                            arguments and returns true if those values should be kept in the
----                            final table
+---@param f fun(...):bool Filter function. Accepts the current iterator or table values as
+---                       arguments and returns true if those values should be kept in the
+---                       final table
 ---@param src table|function Table or iterator function to filter
 ---@return table
 function M.filter(f, src, ...)
@@ -1124,9 +1124,9 @@ end
 ---
 ---@see |Iter:map()|
 ---
----@param f function(...):?any Map function. Accepts the current iterator or table values as
----                            arguments and returns one or more new values. Nil values are removed
----                            from the final table.
+---@param f fun(...): any? Map function. Accepts the current iterator or table values as
+---                        arguments and returns one or more new values. Nil values are removed
+---                        from the final table.
 ---@param src table|function Table or iterator function to filter
 ---@return table
 function M.map(f, src, ...)

runtime/lua/vim/lsp/handlers.lua

@@ -516,7 +516,7 @@ end
 ---
 --- Displays call hierarchy in the quickfix window.
 ---
----@param direction `"from"` for incoming calls and `"to"` for outgoing calls
+---@param direction 'from'|'to' `"from"` for incoming calls and `"to"` for outgoing calls
 ---@return function
 --- `CallHierarchyIncomingCall[]` if {direction} is `"from"`,
 --- `CallHierarchyOutgoingCall[]` if {direction} is `"to"`,

runtime/lua/vim/lsp/util.lua

@@ -790,7 +790,7 @@ end
 --- Note that if the input is of type `MarkupContent` and its kind is `plaintext`,
 --- then the corresponding value is returned without further modifications.
 ---
----@param input (`MarkedString` | `MarkedString[]` | `MarkupContent`)
+---@param input (lsp.MarkedString | lsp.MarkedString[] | lsp.MarkupContent)
 ---@param contents (table|nil) List of strings to extend with converted lines. Defaults to {}.
 ---@return string[] extended with lines of converted markdown.
 ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover
@@ -2115,8 +2115,8 @@ end
 --- Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer.
 ---
 ---@param buf integer buffer number (0 for current)
----@param row 0-indexed line
----@param col 0-indexed byte offset in line
+---@param row integer 0-indexed line
+---@param col integer 0-indexed byte offset in line
 ---@param offset_encoding string utf-8|utf-16|utf-32 defaults to `offset_encoding` of first client of `buf`
 ---@return integer `offset_encoding` index of the character in line {row} column {col} in buffer {buf}
 function M.character_offset(buf, row, col, offset_encoding)

runtime/lua/vim/shared.lua

@@ -875,7 +875,7 @@ end
 --- a.b.c = 1
 --- ```
 ---
----@param createfn function?(key:any):any Provides the value for a missing `key`.
+---@param createfn? fun(key:any):any Provides the value for a missing `key`.
 ---@return table # Empty table with `__index` metamethod.
 function vim.defaulttable(createfn)
   createfn = createfn or function(_)

runtime/lua/vim/treesitter/query.lua

@@ -793,7 +793,7 @@ end
 --- of the query file, e.g., if the path ends in `/lua/highlights.scm`, the parser for the
 --- `lua` language will be used.
 ---@param buf (integer) Buffer handle
----@param opts (QueryLinterOpts|nil) Optional keyword arguments:
+---@param opts? QueryLinterOpts (table) Optional keyword arguments:
 ---   - langs (string|string[]|nil) Language(s) to use for checking the query.
 ---            If multiple languages are specified, queries are validated for all of them
 ---   - clear (boolean) if `true`, just clear current lint errors