feat(api): optional params after `opts` #40720

Problem:
After 25439dad7e2b, `opts` is optional, but not params that follow it.

Solution:
- Update `gen_api_dispatch.lua`, docs, tests.
- Enhance the `nvim_get_api_info()` api-metadata to include a boolean
  flag indicating whether a parameter is optional:
  ```
  [type, name, optional]
  ```

Note: Currently, optional params are assumed to be Dict/Array. Since we
don't yet have any use-cases of optional params following `opts`, the
build just checks this assumption and we can deal with it later if we
ever care to:

    nvim_get_hl: optional param "foo" has type "Integer" but (currently)
    we assume Dict/Array

1 files changed, 2 insertions, 2 deletions

diff --git a/runtime/lua/vim/pos.lua b/runtime/lua/vim/pos.lua
index 9f1f61b446..df55e5e431 100644
--- a/runtime/lua/vim/pos.lua
+++ b/runtime/lua/vim/pos.lua
@@ -210,7 +210,7 @@ end
 ---
 --- -- Convert to mark position, you can call it in a method style.
 --- local lnum, col = pos:to_mark()
---- vim.api.nvim_buf_set_mark(0, 'M', lnum, col, {})
+--- vim.api.nvim_buf_set_mark(0, 'M', lnum, col)
 --- ```
 ---@param pos vim.Pos
 ---@return integer lnum, integer col
@@ -223,7 +223,7 @@ end
 ---
 --- Example:
 --- ```lua
---- local mark_info = vim.api.nvim_get_mark('M', {})
+--- local mark_info = vim.api.nvim_get_mark('M')
 --- local lnum, col, buf, name = unpack(mark_info)
 ---
 --- if lnum == 0 and col == 0 and buf == 0 then