Problem: There is no easy way to configure the behavior of the default
diagnostic "jump" mappings. For example, some users way want to show the
floating window, and some may not (likewise, some way want to only move
between warnings/errors, or disable the "wrap" parameter).
Solution: Add a "jump" table to vim.diagnostic.config() that sets
default values for vim.diagnostic.jump().
Alternatives: Users can override the default mappings to use the exact
options to vim.diagnostic.jump() that they want, but this has a couple
issues:
- While the default mappings are not complicated, they are also not
trivial, so overriding them requires users to understand
implementation details (specifically things like setting "count"
properly).
- If plugins want to change the default mappings, or configure the
behavior in any way (e.g. floating window display), it becomes even
harder for users to tweak specific behavior.
vim.diagnostic.config() already works quite well as the "entry point"
for tuning knobs with diagnostic UI elements, so this fits in nicely and
composes well with existing mental models and idioms.
Deprecate vim.diagnostic.goto_prev() and vim.diagnostic.goto_next() in
favor of a unified vim.diagnostic.jump() interface.
We cannot name the function "goto()" because some of our tooling
(luacheck and stylua) fail to parse it, presumably because "goto" is a
keyword in newer versions of Lua.
vim.diagnostic.jump() also allows moving to a specific diagnostic and
moving by multiple diagnostics at a time (useful for creating mappings
that use v:count).
Deprecation with vim.deprecate is currently too noisy. Show the
following warning instead:
[function] is deprecated. Run ":checkhealth vim.deprecated" for more information.
The important part is that the full message needs to be short enough to
fit in one line in order to not trigger the "Press ENTER or type command
to continue" prompt.
The full information and stack trace for the deprecated functions will
be shown in the new healthcheck `vim.deprecated`.
Problem: On nvim 11.0-dev, deprecation warnings due to an use of
hard-deprecated APIs such as:
- `vim.diagnostic.disable()`
- `vim.diagnostic.is_disabled()`
etc. are not accompanied by backtrace information. It makes difficult
for users to figure out which lines or which plugins are still using
deprecated APIs.
Solution: use `backtrace = true` in vim.deprecate() call.
Follow-up to #28490
Problem:
The new behaviour of goto_next/prev() of navigating to the next highest
severity doesn't work well when diagnostic providers have different
interpretations of severities. E.g. the user may be blocked from
navigating to a useful LSP warning, due to some linter error.
Solution:
The behaviour of next highest severity is now a hidden option
`_highest = true`. We can revisit how to integrate this behaviour
during the 0.11 cycle.
Problem:
The new LSP "refactor menu" keybinding "crr" is also defined in visual
mode, which overlaps with the builtin "c".
Solution:
Use CTRL-R instead of "crr" for visual mode.
fix#28528
Problem: when line is blank link then there will got an invalid column number in math.min compare.
Solution: make sure the min column number is 0 not an illegal number.
Instead of adding all diagnostics matching lnum filters to a table, and
then copying that table to another table while applying the severity
filter, this changes the flow to only add diagnostics matching both
filters in the first pass.
Problem:
We need to establish a pattern for `enable()`.
Solution:
- First `enable()` parameter is always `enable:boolean`.
- Update `vim.diagnostic.enable()`
- Update `vim.lsp.inlay_hint.enable()`.
- It was not released yet, so no deprecation is needed. But to help
HEAD users, it will show an informative error.
- vim.deprecate():
- Improve message when the "removal version" is a *current or older* version.
Problem:
vim.diagnostic.enable() does not match the signature of vim.lsp.inlay_hint.enable()
Solution:
- Change the signature so that the first 2 args are (bufnr, enable).
- Introduce a 3rd `opts` arg.
- Currently it only supports `opts.ns_id`.
Problem:
`vim.diagnostic.is_disabled` and `vim.diagnostic.disable` are unnecessary
and inconsistent with the "toggle" pattern (established starting with
`vim.lsp.inlay_hint`, see https://github.com/neovim/neovim/pull/25512#pullrequestreview-1676750276
As a reminder, the rationale is:
- we always need `enable()`
- we always end up needing `is_enabled()`
- "toggle" can be achieved via `enable(not is_enabled())`
- therefore,
- `toggle()` and `disable()` are redundant
- `is_disabled()` is a needless inconsistency
Solution:
- Introduce `vim.diagnostic.is_enabled`, and `vim.diagnostic.enable(…, enable:boolean)`
- Note: Future improvement would be to add an `enable()` overload `enable(enable:boolean, opts: table)`.
- Deprecate `vim.diagnostic.is_disabled`, `vim.diagnostic.disable`
- 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.
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).
The benefit of this is that users only pay for what they use. If e.g.
only `vim.lsp.buf_get_clients()` is called then they don't need to load
all modules under `vim.lsp` which could lead to significant startuptime
saving.
Also `vim.lsp.module` is a bit nicer to user compared to
`require("vim.lsp.module")`.
This isn't used for some nested modules such as `filetype` as it breaks
tests with error messages such as "attempt to index field 'detect'".
It's not entirely certain the reason for this, but it is likely it is
due to filetype being precompiled which would imply deferred loading
isn't needed for performance reasons.
Problem: vim.diagnostic.{underline,float,virtual_text...}.severity
will have a type warning on list-like or table (min-max) inputs,
e.g. `vim.diagnostic.config { float = { severity = { min = INFO } } }`.
Solution: Correct the typing as documented in |diagnostic-severity|.
Problem:
Currently `deepcopy` hashes every single tables it copies so it can be
reused. For tables of mostly unique items that are non recursive, this
hashing is unnecessarily expensive
Solution:
Port the `noref` argument from Vimscripts `deepcopy()`.
The below benchmark demonstrates the results for two extreme cases of
tables of different sizes. One table that uses the same table lots of
times and one with all unique tables.
| test | `noref=false` (ms) | `noref=true` (ms) |
| -------------------- | ------------------ | ----------------- |
| unique tables (50) | 6.59 | 2.62 |
| shared tables (50) | 3.24 | 6.40 |
| unique tables (2000) | 23381.48 | 2884.53 |
| shared tables (2000) | 3505.54 | 14038.80 |
The results are basically the inverse of each other where `noref` is
much more performance on tables with unique fields, and `not noref` is
more performant on tables that reuse fields.
feat(diagnostic): add `vim.diagnostic.count()`
Problem: Getting diagnostic count based on the output of
`vim.diagnostic.get()` might become costly as number of diagnostic
entries grows. This is because it returns a copy of diagnostic cache
entries (so as to not allow users to change them in place).
Getting information about diagnostic count is frequently used in
statusline, so it is important to be as fast as reasonbly possible.
Solution: Add `vim.diagnostic.count()` which computes severity
counts without making copies.
Diagnostic signs should now be configured with vim.diagnostic.config(),
but "legacy" sign definitions should go through the standard deprecation
process to minimize the impact from breaking changes.
Anonymous namespaces are more difficult to extend or hook into since
they do not appear in the output of nvim_get_namespaces(). Use named
namespaces instead.
The prefix option of the diagnostic virtual text can be a function,
but previously it was only a function of diagnostic.
This function should also have additional parameters index and total,
more consistently and similarily as in the prefix function for
`vim.diagnostic.open_float()`.
These additional parameters will be useful when there are too many
number of diagnostics in a single line.
Problem:
When enabling diagnostics, there can be diagnostics for unloaded buffer,
but some handlers nevertheless attempt to set extmarks in such buffers.
Solution:
* Exit underline/virtual_text handler if buffer is not loaded.
* Don't require is_loaded as precondition for show(), because handlers
don't necessarily depend on it.
Problem: luals returns stricter diagnostics with bundled luarc.json
Solution: Improve some function and type annotations:
* use recognized uv.* types
* disable diagnostic for global `vim` in shared.lua
* docs: don't start comment lines with taglink (otherwise LuaLS will interpret it as a type)
* add type alias for lpeg pattern
* fix return annotation for `vim.secure.trust`
* rename local Range object in vim.version (shadows `Range` in vim.treesitter)
* fix some "missing fields" warnings
* add missing required fields for test functions in eval.lua
* rename lsp meta files for consistency
* 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>
