docs(vvars): adjust lua types for vim.v variables #31510

- classes for v:event and v:completed_item
- add remaining unknown types

3 files changed, 97 insertions, 10 deletions

diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index 264907109f..445da4e02f 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -15,7 +15,7 @@ vim.v.argv = ...
 --- Argument for evaluating 'formatexpr' and used for the typed
 --- character when using <expr> in an abbreviation `:map-<expr>`.
 --- It is also used by the `InsertCharPre` and `InsertEnter` events.
---- @type any
+--- @type string
 vim.v.char = ...
 
 --- The name of the character encoding of a file to be converted.
@@ -60,7 +60,7 @@ vim.v.collate = ...
 --- mode.
 --- Note: Plugins can modify the value to emulate the builtin
 --- `CompleteDone` event behavior.
---- @type any
+--- @type vim.v.completed_item
 vim.v.completed_item = ...
 
 --- The count given for the last Normal mode command.  Can be used
@@ -90,7 +90,7 @@ vim.v.count1 = ...
 --- This variable can not be set directly, use the `:language`
 --- command.
 --- See `multi-lang`.
---- @type any
+--- @type string
 vim.v.ctype = ...
 
 --- Normally zero.  When a deadly signal is caught it's set to
@@ -199,7 +199,7 @@ vim.v.errors = ...
 ---   reason           Reason for completion being done. `CompleteDone`
 ---   complete_word    The word that was selected, empty if abandoned complete.
 ---   complete_type    See `complete_info_mode`
---- @type any
+--- @type vim.v.event
 vim.v.event = ...
 
 --- The value of the exception most recently caught and not
@@ -225,7 +225,7 @@ vim.v.exception = ...
 --- ```vim
 ---   :au VimLeave * echo "Exit value is " .. v:exiting
 --- ```
---- @type any
+--- @type integer?
 vim.v.exiting = ...
 
 --- Special value used to put "false" in JSON and msgpack.  See
@@ -421,7 +421,7 @@ vim.v.mouse_winid = ...
 --- and `msgpackdump()`. All types inside dictionary are fixed
 --- (not editable) empty lists. To check whether some list is one
 --- of msgpack types, use `is` operator.
---- @type any
+--- @type table
 vim.v.msgpack_types = ...
 
 --- Special value used to put "null" in JSON and NIL in msgpack.
@@ -565,7 +565,7 @@ vim.v.relnum = ...
 --- typed command.
 --- This can be used to find out why your script causes the
 --- hit-enter prompt.
---- @type any
+--- @type string
 vim.v.scrollstart = ...
 
 --- Search direction:  1 after a forward search, 0 after a
@@ -707,13 +707,13 @@ vim.v.termrequest = ...
 vim.v.termresponse = ...
 
 --- Must be set before using `test_garbagecollect_now()`.
---- @type any
+--- @type integer
 vim.v.testing = ...
 
 --- Full filename of the last loaded or saved session file.
 --- Empty when no session file has been saved.  See `:mksession`.
 --- Modifiable (can be set).
---- @type any
+--- @type string
 vim.v.this_session = ...
 
 --- The point where the exception most recently caught and not
@@ -730,7 +730,7 @@ vim.v.this_session = ...
 --- ```
 ---
 --- Output: "Exception from test.vim, line 2"
---- @type any
+--- @type string
 vim.v.throwpoint = ...
 
 --- Special value used to put "true" in JSON and msgpack.  See
diff --git a/runtime/lua/vim/_meta/vvars_extra.lua b/runtime/lua/vim/_meta/vvars_extra.lua
new file mode 100644
index 0000000000..7ef3021e89
--- /dev/null
+++ b/runtime/lua/vim/_meta/vvars_extra.lua
@@ -0,0 +1,77 @@
+--- @meta _
+error('Cannot require a meta file')
+
+--- Extra types for vim.v dictionary fields
+
+--- @class vim.v.completed_item
+--- @field word? string the text that will be inserted, mandatory
+--- abbreviation of "word"; when not empty it is used in the menu instead of "word"
+--- @field abbr? string
+--- extra text for the popup menu, displayed after "word" or "abbr"
+--- @field menu? string
+--- more information about the item, can be displayed in a preview window
+--- @field info? string
+--- @field kind? string single letter indicating the type of completion
+--- when non-zero case is to be ignored when comparing items to be equal; when
+--- omitted zero is used, thus items that only differ in case are added
+--- @field icase? integer
+--- when non-zero, always treat this item to be equal when comparing. Which
+--- means, "equal=1" disables filtering of this item.
+--- @field equal? integer
+--- when non-zero this match will be added even when an item with the same word
+--- is already present.
+--- @field dup? integer
+--- when non-zero this match will be added even when it is an empty string
+--- @field empty? integer
+--- custom data which is associated with the item and available
+--- in |v:completed_item|; it can be any type; defaults to an empty string
+--- @field user_data? any
+--- an additional highlight group whose attributes are combined
+--- with |hl-PmenuSel| and |hl-Pmenu| or |hl-PmenuMatchSel| and |hl-PmenuMatch|
+--- highlight attributes in the popup menu to apply cterm and gui properties
+--- (with higher priority) like strikethrough to the completion items abbreviation
+--- @field abbr_hlgroup? string
+--- an additional highlight group specifically for setting the highlight
+--- attributes of the completion kind. When this field is present, it will
+--- override the |hl-PmenuKind| highlight group, allowing for the customization
+--- of ctermfg and guifg properties for the completion kind
+--- @field kind_hlgroup? string
+
+--- @class vim.v.event
+--- Whether the event triggered during an aborting condition (e.g. |c_Esc| or
+--- |c_CTRL-C| for |CmdlineLeave|).
+--- @field abort? boolean
+--- @field chan? integer See |channel-id|
+--- @field info? table Dict of arbitrary event data.
+--- @field cmdlevel? integer Level of cmdline.
+--- @field cmdtype? string Type of cmdline, |cmdline-char|.
+--- @field cwd? string Current working directory.
+--- @field inclusive? boolean Motion is |inclusive|, else exclusive.
+--- @field scope? string Event-specific scope name.
+--- Current |operator|. Also set for Ex commands (unlike |v:operator|). For
+--- example if |TextYankPost| is triggered by the |:yank| Ex command then
+--- `v:event.operator` is "y".
+--- @field operator? string
+--- Text stored in the register as a |readfile()|-style list of lines.
+--- @field regcontents? string
+--- Requested register (e.g "x" for "xyy) or the empty string for an unnamed operation.
+--- @field regname? string
+--- @field regtype? string Type of register as returned by |getregtype()|.
+--- @field visual? boolean Selection is visual (as opposed to, e.g., via motion).
+--- @field completed_item? vim.v.completed_item
+--- Current selected complete item on |CompleteChanged|, Is `{}` when no
+--- complete item selected.
+--- @field height? integer
+--- @field width? integer Height of popup menu on |CompleteChanged|
+--- @field row? integer Width of popup menu on |CompleteChanged|
+--- Col count of popup menu on |CompleteChanged|, relative to screen.
+--- @field col? integer
+--- @field size? integer Total number of completion items on |CompleteChanged|.
+--- Is |v:true| if popup menu have scrollbar, or |v:false| if not.
+--- @field scrollbar? boolean
+--- Is |v:true| if the event fired while changing window  (or tab) on |DirChanged|.
+--- @field changed_window? boolean
+--- @field status? boolean Job status or exit code, -1 means "unknown". |TermClose|
+--- @field reason? string Reason for completion being done. |CompleteDone|
+--- The word that was selected, empty if abandoned complete. @field complete_word? string
+--- @field complete_type? string See |complete_info_mode|
diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua
index f1b8c22bdd..e705c02e83 100644
--- a/src/nvim/vvars.lua
+++ b/src/nvim/vvars.lua
@@ -10,6 +10,7 @@ M.vars = {
     ]=],
   },
   char = {
+    type = 'string',
     desc = [=[
       Argument for evaluating 'formatexpr' and used for the typed
       character when using <expr> in an abbreviation |:map-<expr>|.
@@ -63,6 +64,7 @@ M.vars = {
     ]=],
   },
   completed_item = {
+    type = 'vim.v.completed_item',
     desc = [=[
       Dictionary containing the |complete-items| for the most
       recently completed word after |CompleteDone|.  Empty if the
@@ -94,6 +96,7 @@ M.vars = {
     ]=],
   },
   ctype = {
+    type = 'string',
     desc = [=[
       The current locale setting for characters of the runtime
       environment.  This allows Vim scripts to be aware of the
@@ -158,6 +161,7 @@ M.vars = {
     ]=],
   },
   event = {
+    type = 'vim.v.event',
     desc = [=[
       Dictionary of event data for the current |autocommand|.  Valid
       only during the event lifetime; storing or passing v:event is
@@ -238,6 +242,7 @@ M.vars = {
     ]=],
   },
   exiting = {
+    type = 'integer?',
     desc = [=[
       Exit code, or |v:null| before invoking the |VimLeavePre|
       and |VimLeave| autocmds.  See |:q|, |:x| and |:cquit|.
@@ -470,6 +475,7 @@ M.vars = {
     ]=],
   },
   msgpack_types = {
+    type = 'table',
     desc = [=[
       Dictionary containing msgpack types used by |msgpackparse()|
       and |msgpackdump()|. All types inside dictionary are fixed
@@ -635,6 +641,7 @@ M.vars = {
     ]=],
   },
   scrollstart = {
+    type = 'string',
     desc = [=[
       String describing the script or function that caused the
       screen to scroll up.  It's only set when it is empty, thus the
@@ -798,11 +805,13 @@ M.vars = {
     ]=],
   },
   testing = {
+    type = 'integer',
     desc = [=[
       Must be set before using `test_garbagecollect_now()`.
     ]=],
   },
   this_session = {
+    type = 'string',
     desc = [=[
       Full filename of the last loaded or saved session file.
       Empty when no session file has been saved.  See |:mksession|.
@@ -810,6 +819,7 @@ M.vars = {
     ]=],
   },
   throwpoint = {
+    type = 'string',
     desc = [=[
       The point where the exception most recently caught and not
       finished was thrown.  Not set when commands are typed.  See