To be more in line with the specification:

> To support the evolution of enumerations the using side of an enumeration shouldn’t fail on an enumeration value it doesn’t know. It should simply ignore it as a value it can use and try to do its best to preserve the value on round trips

Follw up to https://github.com/neovim/neovim/commit/63b3408551561127f7845470eb51404bcd6f547b

`is_pull` should be optional, otherwise it is an API change that
introduces warnings in consumers.

Also fixes the type annotation of `_client_pull_namespaces` where the
key is a string.

This fixes the issue where the LspNotify handlers for inlay_hint /
diagnostics would end up refreshing all attached clients.

The handler would call util._refresh, which called
vim.lsp.buf_request, which calls the method on all attached clients.

Now util._refresh takes an optional client_id parameter, which is used
to specify a specific client to update.

This commit also fixes util._refresh's handling of the `only_visible`
flag. Previously if `only_visible` was false, two requests would be made
to the server: one for the visible region, and one for the entire file.

Co-authored-by: Stanislav Asunkin <1353637+stasjok@users.noreply.github.com>
Co-authored-by: Mathias Fußenegger <mfussenegger@users.noreply.github.com>

Problem:
"Failed to delete autocmd" error when deleting LspNotify autocmd. #24456

Solution:
Change a few things in the inlay_hint and diagnostic LSP code:
1. Re-introduce the `enabled` flag for the buffer state tables. Previously I was
   relying on the presence of an autocmd id in the state table to track whether
   inlay_hint / diagnostic was enabled for a buffer. There are two reasons why
   this doesn't work well:
  - Each time inlay_hint / diagnostic is enabled, we call `nvim_buf_attach` on
    the buffer, resulting in multiple `on_reload` or `on_detach` callbacks being
    registered.
  - Commands like `bwipeout` delete buffer local autocmds, sometimes before our
    `on_detach` callbacks have a chance to delete them first. This causes the
  - Use module local enabled state for diagnostic as well. bwipeout can race
    with on_detach callbacks for deleting autocmds. Error referenced in #24456.
2. Change the `LspDetach` autocmd to run each time (i.e., remove the `once`
   flag). Since we're only registering autocmds once per buffer now, we
   need to make sure that we set the enabled flag properly each time the LSP
   client detaches from the buffer.
  - Remove `once` from the LspDetach autocmds for inlay_hint and diagnostic.
    We only set up the autocmd once now. Gets removed when buffer is deleted.
3. Have the `LspNotify` handler also refresh the inlay_hint / diagnostics when
   receiving the `textDocument/didOpen` event. Before this point, the LSP
   backend doesn't have the contents of the buffer, so can't provide inlay hints
   or diagnostics.

Downsides of this approach:
* When inlay_hint / diagnostics are disabled on a buffer, it will continue to
  receive `LspNotify` events for that buffer. The callback exits early since the
  `enabled` flag is false.

Alternatives:
* Can we wrap the call to `nvim_del_autocmd` in `pcall` to swallow any errors
  resulting from trying to delete the autocmd?

Fixes #24456

Helped-by: Maria José Solano <majosolano99@gmail.com>

* docs(lua): teach lua2dox how to table

* docs(lua): teach gen_vimdoc.py about local functions

No more need to mark local functions with @private

* docs(lua): mention @nodoc and @meta in dev-lua-doc

* fixup!

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

---------

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

LSP tags are added to the diagnostic as "tags" but referred to as "_tags"
in the diagnostic underline handler

The LSP spec supports two tags that can be added to diagnostics:
unnecessary and deprecated. Extend vim.diagnostic to be able to handle
these.