From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Thu, 15 Feb 2024 17:16:04 +0000
Subject: feat(docs): replace lua2dox.lua

Problem:

The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.

Solution:

Re-implement the flow using Lua, LPEG and treesitter.

- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
  - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
  - LPEG for C parsing (see `scripts/cdoc_parser.lua`)
  - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
  - Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
   - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
---
 runtime/lua/vim/_options.lua | 356 +++++++++++++++++++++----------------------
 1 file changed, 171 insertions(+), 185 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index b83a8dd4b1..f1fed50c6d 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -1,12 +1,10 @@
----@defgroup lua-vimscript
+--- @brief Nvim Lua provides an interface or "bridge" to Vimscript variables and
+--- functions, and editor commands and options.
 ---
----@brief Nvim Lua provides an interface or "bridge" to Vimscript variables and
----functions, and editor commands and options.
----
----Objects passed over this bridge are COPIED (marshalled): there are no
----"references". |lua-guide-variables| For example, using \`vim.fn.remove()\` on
----a Lua list copies the list object to Vimscript and does NOT modify the Lua
----list:
+--- Objects passed over this bridge are COPIED (marshalled): there are no
+--- "references". |lua-guide-variables| For example, using `vim.fn.remove()` on
+--- a Lua list copies the list object to Vimscript and does NOT modify the Lua
+--- list:
 ---
 --- ```lua
 --- local list = { 1, 2, 3 }
@@ -14,86 +12,85 @@
 --- vim.print(list)  --> "{ 1, 2, 3 }"
 --- ```
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.call({func}, {...})                                           *vim.call()*
----    Invokes |vim-function| or |user-function| {func} with arguments {...}.
----    See also |vim.fn|.
----    Equivalent to: >lua
----        vim.fn[func]({...})
----<
----vim.cmd({command})
----    See |vim.cmd()|.
----
----vim.fn.{func}({...})                                                  *vim.fn*
----    Invokes |vim-function| or |user-function| {func} with arguments {...}.
----    To call autoload functions, use the syntax: >lua
----        vim.fn['some\#function']({...})
----<
----    Unlike vim.api.|nvim_call_function()| this converts directly between Vim
----    objects and Lua objects. If the Vim function returns a float, it will be
----    represented directly as a Lua number. Empty lists and dictionaries both
----    are represented by an empty table.
----
----    Note: |v:null| values as part of the return value is represented as
----    |vim.NIL| special value
----
----    Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
----    enumerates functions that were called at least once.
----
----    Note: The majority of functions cannot run in |api-fast| callbacks with some
----    undocumented exceptions which are allowed.
----
----                                                           *lua-vim-variables*
----The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed
----from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
----described below. In this way you can easily read and modify global Vimscript
----variables from Lua.
----
----Example: >lua
----
----    vim.g.foo = 5     -- Set the g:foo Vimscript variable.
----    print(vim.g.foo)  -- Get and print the g:foo Vimscript variable.
----    vim.g.foo = nil   -- Delete (:unlet) the Vimscript variable.
----    vim.b[2].foo = 6  -- Set b:foo for buffer 2
----<
----
----Note that setting dictionary fields directly will not write them back into
----Nvim. This is because the index into the namespace simply returns a copy.
----Instead the whole dictionary must be written as one. This can be achieved by
----creating a short-lived temporary.
----
----Example: >lua
----
----    vim.g.my_dict.field1 = 'value'  -- Does not work
----
----    local my_dict = vim.g.my_dict   --
----    my_dict.field1 = 'value'        -- Instead do
----    vim.g.my_dict = my_dict         --
----
----vim.g                                                                  *vim.g*
----    Global (|g:|) editor variables.
----    Key with no value returns `nil`.
----
----vim.b                                                                  *vim.b*
----    Buffer-scoped (|b:|) variables for the current buffer.
----    Invalid or unset key returns `nil`. Can be indexed with
----    an integer to access variables for a specific buffer.
----
----vim.w                                                                  *vim.w*
----    Window-scoped (|w:|) variables for the current window.
----    Invalid or unset key returns `nil`. Can be indexed with
----    an integer to access variables for a specific window.
----
----vim.t                                                                  *vim.t*
----    Tabpage-scoped (|t:|) variables for the current tabpage.
----    Invalid or unset key returns `nil`. Can be indexed with
----    an integer to access variables for a specific tabpage.
----
----vim.v                                                                  *vim.v*
----    |v:| variables.
----    Invalid or unset key returns `nil`.
----</pre>
+--- @brief <pre>help
+--- vim.call({func}, {...})                                           *vim.call()*
+---     Invokes |vim-function| or |user-function| {func} with arguments {...}.
+---     See also |vim.fn|.
+---     Equivalent to: >lua
+---         vim.fn[func]({...})
+--- <
+--- vim.cmd({command})
+---     See |vim.cmd()|.
+---
+--- vim.fn.{func}({...})                                                  *vim.fn*
+---     Invokes |vim-function| or |user-function| {func} with arguments {...}.
+---     To call autoload functions, use the syntax: >lua
+---         vim.fn['some#function']({...})
+--- <
+---     Unlike vim.api.|nvim_call_function()| this converts directly between Vim
+---     objects and Lua objects. If the Vim function returns a float, it will be
+---     represented directly as a Lua number. Empty lists and dictionaries both
+---     are represented by an empty table.
+---
+---     Note: |v:null| values as part of the return value is represented as
+---     |vim.NIL| special value
+---
+---     Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
+---     enumerates functions that were called at least once.
+---
+---     Note: The majority of functions cannot run in |api-fast| callbacks with some
+---     undocumented exceptions which are allowed.
+---
+---                                                            *lua-vim-variables*
+--- The Vim editor global dictionaries |g:| |w:| |b:| |t:| |v:| can be accessed
+--- from Lua conveniently and idiomatically by referencing the `vim.*` Lua tables
+--- described below. In this way you can easily read and modify global Vimscript
+--- variables from Lua.
+---
+--- Example: >lua
+---
+---     vim.g.foo = 5     -- Set the g:foo Vimscript variable.
+---     print(vim.g.foo)  -- Get and print the g:foo Vimscript variable.
+---     vim.g.foo = nil   -- Delete (:unlet) the Vimscript variable.
+---     vim.b[2].foo = 6  -- Set b:foo for buffer 2
+--- <
+---
+--- Note that setting dictionary fields directly will not write them back into
+--- Nvim. This is because the index into the namespace simply returns a copy.
+--- Instead the whole dictionary must be written as one. This can be achieved by
+--- creating a short-lived temporary.
+---
+--- Example: >lua
+---
+---     vim.g.my_dict.field1 = 'value'  -- Does not work
+---
+---     local my_dict = vim.g.my_dict   --
+---     my_dict.field1 = 'value'        -- Instead do
+---     vim.g.my_dict = my_dict         --
+---
+--- vim.g                                                                  *vim.g*
+---     Global (|g:|) editor variables.
+---     Key with no value returns `nil`.
+---
+--- vim.b                                                                  *vim.b*
+---     Buffer-scoped (|b:|) variables for the current buffer.
+---     Invalid or unset key returns `nil`. Can be indexed with
+---     an integer to access variables for a specific buffer.
+---
+--- vim.w                                                                  *vim.w*
+---     Window-scoped (|w:|) variables for the current window.
+---     Invalid or unset key returns `nil`. Can be indexed with
+---     an integer to access variables for a specific window.
+---
+--- vim.t                                                                  *vim.t*
+---     Tabpage-scoped (|t:|) variables for the current tabpage.
+---     Invalid or unset key returns `nil`. Can be indexed with
+---     an integer to access variables for a specific tabpage.
+---
+--- vim.v                                                                  *vim.v*
+---     |v:| variables.
+---     Invalid or unset key returns `nil`.
+--- </pre>
 
 local api = vim.api
 
@@ -142,7 +139,6 @@ end
 --- vim.env.FOO = 'bar'
 --- print(vim.env.TERM)
 --- ```
----
 ---@param var string
 vim.env = setmetatable({}, {
   __index = function(_, k)
@@ -205,31 +201,30 @@ local function new_win_opt_accessor(winid, bufnr)
   })
 end
 
----@addtogroup lua-vimscript
----@brief <pre>help
----` `                                                                *lua-options*
----                                                             *lua-vim-options*
----                                                                 *lua-vim-set*
----                                                            *lua-vim-setlocal*
+--- @brief <pre>help
+---                                                                  *lua-options*
+---                                                              *lua-vim-options*
+---                                                                  *lua-vim-set*
+---                                                             *lua-vim-setlocal*
 ---
----Vim options can be accessed through |vim.o|, which behaves like Vimscript
----|:set|.
+--- Vim options can be accessed through |vim.o|, which behaves like Vimscript
+--- |:set|.
 ---
----    Examples: ~
+---     Examples: ~
 ---
----    To set a boolean toggle:
----        Vimscript: `set number`
----        Lua:       `vim.o.number = true`
+---     To set a boolean toggle:
+---         Vimscript: `set number`
+---         Lua:       `vim.o.number = true`
 ---
----    To set a string value:
----        Vimscript: `set wildignore=*.o,*.a,__pycache__`
----        Lua:       `vim.o.wildignore = '*.o,*.a,__pycache__'`
+---     To set a string value:
+---         Vimscript: `set wildignore=*.o,*.a,__pycache__`
+---         Lua:       `vim.o.wildignore = '*.o,*.a,__pycache__'`
 ---
----Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and
----window-scoped options. Note that this must NOT be confused with
----|local-options| and |:setlocal|. There is also |vim.go| that only accesses the
----global value of a |global-local| option, see |:setglobal|.
----</pre>
+--- Similarly, there is |vim.bo| and |vim.wo| for setting buffer-scoped and
+--- window-scoped options. Note that this must NOT be confused with
+--- |local-options| and |:setlocal|. There is also |vim.go| that only accesses the
+--- global value of a |global-local| option, see |:setglobal|.
+--- </pre>
 
 --- Get or set |options|. Like `:set`. Invalid key is an error.
 ---
@@ -310,13 +305,10 @@ vim.bo = new_buf_opt_accessor()
 --- ```
 vim.wo = new_win_opt_accessor()
 
----@brief [[
 --- vim.opt, vim.opt_local and vim.opt_global implementation
 ---
 --- To be used as helpers for working with options within neovim.
 --- For information on how to use, see :help vim.opt
----
----@brief ]]
 
 --- Preserves the order and does not mutate the original list
 local function remove_duplicate_values(t)
@@ -739,74 +731,73 @@ local function create_option_accessor(scope)
   })
 end
 
----@addtogroup lua-vimscript
----@brief <pre>help
----` `                                                                       *vim.opt_local*
----                                                                       *vim.opt_global*
----                                                                              *vim.opt*
----
----
----A special interface |vim.opt| exists for conveniently interacting with list-
----and map-style option from Lua: It allows accessing them as Lua tables and
----offers object-oriented method for adding and removing entries.
----
----    Examples: ~
----
----    The following methods of setting a list-style option are equivalent:
----        In Vimscript: >vim
----            set wildignore=*.o,*.a,__pycache__
----<
----        In Lua using `vim.o`: >lua
----            vim.o.wildignore = '*.o,*.a,__pycache__'
----<
----        In Lua using `vim.opt`: >lua
----            vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
----<
----    To replicate the behavior of |:set+=|, use: >lua
----
----        vim.opt.wildignore:append { "*.pyc", "node_modules" }
----<
----    To replicate the behavior of |:set^=|, use: >lua
----
----        vim.opt.wildignore:prepend { "new_first_value" }
----<
----    To replicate the behavior of |:set-=|, use: >lua
----
----        vim.opt.wildignore:remove { "node_modules" }
----<
----    The following methods of setting a map-style option are equivalent:
----        In Vimscript: >vim
----            set listchars=space:_,tab:>~
----<
----        In Lua using `vim.o`: >lua
----            vim.o.listchars = 'space:_,tab:>~'
----<
----        In Lua using `vim.opt`: >lua
----            vim.opt.listchars = { space = '_', tab = '>~' }
----<
----
----Note that |vim.opt| returns an `Option` object, not the value of the option,
----which is accessed through |vim.opt:get()|:
----
----    Examples: ~
----
----    The following methods of getting a list-style option are equivalent:
----        In Vimscript: >vim
----            echo wildignore
----<
----        In Lua using `vim.o`: >lua
----            print(vim.o.wildignore)
----<
----        In Lua using `vim.opt`: >lua
----            vim.print(vim.opt.wildignore:get())
----<
----
----In any of the above examples, to replicate the behavior |:setlocal|, use
----`vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use
----`vim.opt_global`.
----</pre>
-
---- @diagnostic disable-next-line:unused-local used for gen_vimdoc
+--- @brief <pre>help
+---                                                                           *vim.opt_local*
+---                                                                        *vim.opt_global*
+---                                                                               *vim.opt*
+---
+---
+--- A special interface |vim.opt| exists for conveniently interacting with list-
+--- and map-style option from Lua: It allows accessing them as Lua tables and
+--- offers object-oriented method for adding and removing entries.
+---
+---     Examples: ~
+---
+---     The following methods of setting a list-style option are equivalent:
+---         In Vimscript: >vim
+---             set wildignore=*.o,*.a,__pycache__
+--- <
+---         In Lua using `vim.o`: >lua
+---             vim.o.wildignore = '*.o,*.a,__pycache__'
+--- <
+---         In Lua using `vim.opt`: >lua
+---             vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
+--- <
+---     To replicate the behavior of |:set+=|, use: >lua
+---
+---         vim.opt.wildignore:append { "*.pyc", "node_modules" }
+--- <
+---     To replicate the behavior of |:set^=|, use: >lua
+---
+---         vim.opt.wildignore:prepend { "new_first_value" }
+--- <
+---     To replicate the behavior of |:set-=|, use: >lua
+---
+---         vim.opt.wildignore:remove { "node_modules" }
+--- <
+---     The following methods of setting a map-style option are equivalent:
+---         In Vimscript: >vim
+---             set listchars=space:_,tab:>~
+--- <
+---         In Lua using `vim.o`: >lua
+---             vim.o.listchars = 'space:_,tab:>~'
+--- <
+---         In Lua using `vim.opt`: >lua
+---             vim.opt.listchars = { space = '_', tab = '>~' }
+--- <
+---
+--- Note that |vim.opt| returns an `Option` object, not the value of the option,
+--- which is accessed through |vim.opt:get()|:
+---
+---     Examples: ~
+---
+---     The following methods of getting a list-style option are equivalent:
+---         In Vimscript: >vim
+---             echo wildignore
+--- <
+---         In Lua using `vim.o`: >lua
+---             print(vim.o.wildignore)
+--- <
+---         In Lua using `vim.opt`: >lua
+---             vim.print(vim.opt.wildignore:get())
+--- <
+---
+--- In any of the above examples, to replicate the behavior |:setlocal|, use
+--- `vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use
+--- `vim.opt_global`.
+--- </pre>
+
+--- @class vim.Option
 local Option = {} -- luacheck: no unused
 
 --- Returns a Lua-representation of the option. Boolean, number and string
@@ -856,9 +847,7 @@ local Option = {} -- luacheck: no unused
 ---     print("J is enabled!")
 --- end
 --- ```
----
 ---@return string|integer|boolean|nil value of option
----@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:get() end
 
 --- Append a value to string-style options. See |:set+=|
@@ -869,7 +858,6 @@ function Option:get() end
 --- vim.opt.formatoptions:append('j')
 --- vim.opt.formatoptions = vim.opt.formatoptions + 'j'
 --- ```
----
 ---@param value string Value to append
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:append(value) end -- luacheck: no unused
@@ -882,7 +870,6 @@ function Option:append(value) end -- luacheck: no unused
 --- vim.opt.wildignore:prepend('*.o')
 --- vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
 --- ```
----
 ---@param value string Value to prepend
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:prepend(value) end -- luacheck: no unused
@@ -895,7 +882,6 @@ function Option:prepend(value) end -- luacheck: no unused
 --- vim.opt.wildignore:remove('*.pyc')
 --- vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
 --- ```
----
 ---@param value string Value to remove
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:remove(value) end -- luacheck: no unused
-- 
cgit 


From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Tue, 27 Feb 2024 15:20:32 +0000
Subject: docs: improve/add documentation of Lua types

- Added `@inlinedoc` so single use Lua types can be inlined into the
  functions docs. E.g.

  ```lua
  --- @class myopts
  --- @inlinedoc
  ---
  --- Documentation for some field
  --- @field somefield integer

  --- @param opts myOpts
  function foo(opts)
  end
  ```

  Will be rendered as

  ```
  foo(opts)

    Parameters:
      - {opts} (table) Object with the fields:
               - somefield (integer) Documentation
                 for some field
  ```

- Marked many classes with with `@nodoc` or `(private)`.
  We can eventually introduce these when we want to.
---
 runtime/lua/vim/_options.lua | 1 +
 1 file changed, 1 insertion(+)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index f1fed50c6d..bde9421552 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -797,6 +797,7 @@ end
 --- `vim.opt_global`.
 --- </pre>
 
+--- @nodoc
 --- @class vim.Option
 local Option = {} -- luacheck: no unused
 
-- 
cgit 


From 3df1211ebc4c7ec4562d0ad0fa51a24569b81e15 Mon Sep 17 00:00:00 2001
From: Luna Saphie Mittelbach <lunarlambda@gmail.com>
Date: Mon, 4 Mar 2024 00:33:09 +0100
Subject: docs(lua): clarify when `vim.bo`/`vim.wo` acts like `:setlocal`
 (#27708)

---
 runtime/lua/vim/_options.lua | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index bde9421552..b661ddfb22 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -271,10 +271,10 @@ vim.go = setmetatable({}, {
 })
 
 --- Get or set buffer-scoped |options| for the buffer with number {bufnr}.
---- Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
---- buffer is used. Invalid {bufnr} or key is an error.
+--- If [{bufnr}] is omitted then the current buffer is used.
+--- Invalid {bufnr} or key is an error.
 ---
---- Note: this is equivalent to both `:set` and `:setlocal`.
+--- Note: this is equivalent to `:setlocal` for |global-local| options and `:set` otherwise.
 ---
 --- Example:
 ---
@@ -287,9 +287,9 @@ vim.go = setmetatable({}, {
 vim.bo = new_buf_opt_accessor()
 
 --- Get or set window-scoped |options| for the window with handle {winid} and
---- buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
---- `:set` otherwise. If [{winid}] is omitted then the current window is
---- used. Invalid {winid}, {bufnr} or key is an error.
+--- buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| option
+--- or if {bufnr} is provided, like `:set` otherwise. If [{winid}] is omitted then
+--- the current window is used. Invalid {winid}, {bufnr} or key is an error.
 ---
 --- Note: only {bufnr} with value `0` (the current buffer in the window) is
 --- supported.
-- 
cgit 


From ea44f74d84f87ce5aff2ef7797be986900bd74a6 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Wed, 6 Mar 2024 10:03:55 +0000
Subject: refactor(types): more fixes

---
 runtime/lua/vim/_options.lua | 64 ++++++++++++++++++++++++++++++++++----------
 1 file changed, 50 insertions(+), 14 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index b661ddfb22..60dcf8c64a 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -105,6 +105,10 @@ local key_value_options = {
   winhl = true,
 }
 
+--- @nodoc
+--- @class vim._option.Info : vim.api.keyset.get_option_info
+--- @field metatype 'boolean'|'string'|'number'|'map'|'array'|'set'
+
 --- Convert a vimoption_T style dictionary to the correct OptionType associated with it.
 ---@return string
 local function get_option_metatype(name, info)
@@ -123,8 +127,10 @@ local function get_option_metatype(name, info)
 end
 
 --- @param name string
+--- @return vim._option.Info
 local function get_options_info(name)
   local info = api.nvim_get_option_info2(name, {})
+  --- @cast info vim._option.Info
   info.metatype = get_option_metatype(name, info)
   return info
 end
@@ -139,7 +145,6 @@ end
 --- vim.env.FOO = 'bar'
 --- print(vim.env.TERM)
 --- ```
----@param var string
 vim.env = setmetatable({}, {
   __index = function(_, k)
     local v = vim.fn.getenv(k)
@@ -311,9 +316,15 @@ vim.wo = new_win_opt_accessor()
 --- For information on how to use, see :help vim.opt
 
 --- Preserves the order and does not mutate the original list
+--- @generic T
+--- @param t T[]
+--- @return T[]
 local function remove_duplicate_values(t)
+  --- @type table, table<any,true>
   local result, seen = {}, {}
-  for _, v in ipairs(t) do
+  for _, v in
+    ipairs(t --[[@as any[] ]])
+  do
     if not seen[v] then
       table.insert(result, v)
     end
@@ -324,8 +335,11 @@ local function remove_duplicate_values(t)
   return result
 end
 
--- Check whether the OptionTypes is allowed for vim.opt
--- If it does not match, throw an error which indicates which option causes the error.
+--- Check whether the OptionTypes is allowed for vim.opt
+--- If it does not match, throw an error which indicates which option causes the error.
+--- @param name any
+--- @param value any
+--- @param types string[]
 local function assert_valid_value(name, value, types)
   local type_of_value = type(value)
   for _, valid_type in ipairs(types) do
@@ -352,6 +366,8 @@ local function tbl_merge(left, right)
   return vim.tbl_extend('force', left, right)
 end
 
+--- @param t table<any,any>
+--- @param value any|any[]
 local function tbl_remove(t, value)
   if type(value) == 'string' then
     t[value] = nil
@@ -380,6 +396,8 @@ local to_vim_value = {
   number = passthrough,
   string = passthrough,
 
+  --- @param info vim._option.Info
+  --- @param value string|table<string,true>
   set = function(info, value)
     if type(value) == 'string' then
       return value
@@ -407,6 +425,8 @@ local to_vim_value = {
     end
   end,
 
+  --- @param info vim._option.Info
+  --- @param value string|string[]
   array = function(info, value)
     if type(value) == 'string' then
       return value
@@ -417,6 +437,7 @@ local to_vim_value = {
     return table.concat(value, ',')
   end,
 
+  --- @param value string|table<string,string>
   map = function(_, value)
     if type(value) == 'string' then
       return value
@@ -466,7 +487,8 @@ local to_lua_value = {
     end
 
     -- Handles unescaped commas in a list.
-    if string.find(value, ',,,') then
+    if value:find(',,,') then
+      --- @type string, string
       local left, right = unpack(vim.split(value, ',,,'))
 
       local result = {}
@@ -479,8 +501,9 @@ local to_lua_value = {
       return result
     end
 
-    if string.find(value, ',^,,', 1, true) then
-      local left, right = unpack(vim.split(value, ',^,,', true))
+    if value:find(',^,,', 1, true) then
+      --- @type string, string
+      local left, right = unpack(vim.split(value, ',^,,', { plain = true }))
 
       local result = {}
       vim.list_extend(result, vim.split(left, ','))
@@ -508,22 +531,20 @@ local to_lua_value = {
 
     assert(info.flaglist, 'That is the only one I know how to handle')
 
+    local result = {} --- @type table<string,true>
+
     if info.flaglist and info.commalist then
       local split_value = vim.split(value, ',')
-      local result = {}
       for _, v in ipairs(split_value) do
         result[v] = true
       end
-
-      return result
     else
-      local result = {}
       for i = 1, #value do
         result[value:sub(i, i)] = true
       end
-
-      return result
     end
+
+    return result
   end,
 
   map = function(info, raw_value)
@@ -533,10 +554,11 @@ local to_lua_value = {
 
     assert(info.commalist, 'Only commas are supported currently')
 
-    local result = {}
+    local result = {} --- @type table<string,string>
 
     local comma_split = vim.split(raw_value, ',')
     for _, key_value_str in ipairs(comma_split) do
+      --- @type string, string
       local key, value = unpack(vim.split(key_value_str, ':'))
       key = vim.trim(key)
 
@@ -582,14 +604,21 @@ local function prepend_value(info, current, new)
 end
 
 local add_methods = {
+  --- @param left integer
+  --- @param right integer
   number = function(left, right)
     return left + right
   end,
 
+  --- @param left string
+  --- @param right string
   string = function(left, right)
     return left .. right
   end,
 
+  --- @param left string[]
+  --- @param right string[]
+  --- @return string[]
   array = function(left, right)
     for _, v in ipairs(right) do
       table.insert(left, v)
@@ -610,6 +639,8 @@ local function add_value(info, current, new)
   )
 end
 
+--- @param t table<any,any>
+--- @param val any
 local function remove_one_item(t, val)
   if vim.tbl_islist(t) then
     local remove_index = nil
@@ -628,6 +659,8 @@ local function remove_one_item(t, val)
 end
 
 local remove_methods = {
+  --- @param left integer
+  --- @param right integer
   number = function(left, right)
     return left - right
   end,
@@ -636,6 +669,9 @@ local remove_methods = {
     error('Subtraction not supported for strings.')
   end,
 
+  --- @param left string[]
+  --- @param right string[]
+  --- @return string[]
   array = function(left, right)
     if type(right) == 'string' then
       remove_one_item(left, right)
-- 
cgit 


From ade1b12f49c3b3914c74847d791eb90ea90b56b7 Mon Sep 17 00:00:00 2001
From: Lewis Russell <lewis6991@gmail.com>
Date: Fri, 8 Mar 2024 12:25:18 +0000
Subject: docs: support inline markdown

- Tags are now created with `[tag]()`
- References are now created with `[tag]`
- Code spans are no longer wrapped
---
 runtime/lua/vim/_options.lua | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'runtime/lua/vim/_options.lua')

diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 60dcf8c64a..13ad6cc58f 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -276,7 +276,7 @@ vim.go = setmetatable({}, {
 })
 
 --- Get or set buffer-scoped |options| for the buffer with number {bufnr}.
---- If [{bufnr}] is omitted then the current buffer is used.
+--- If {bufnr} is omitted then the current buffer is used.
 --- Invalid {bufnr} or key is an error.
 ---
 --- Note: this is equivalent to `:setlocal` for |global-local| options and `:set` otherwise.
@@ -293,7 +293,7 @@ vim.bo = new_buf_opt_accessor()
 
 --- Get or set window-scoped |options| for the window with handle {winid} and
 --- buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| option
---- or if {bufnr} is provided, like `:set` otherwise. If [{winid}] is omitted then
+--- or if {bufnr} is provided, like `:set` otherwise. If {winid} is omitted then
 --- the current window is used. Invalid {winid}, {bufnr} or key is an error.
 ---
 --- Note: only {bufnr} with value `0` (the current buffer in the window) is
-- 
cgit