Problem: Some lines in the generated vim doc are overflowing, not
correctly wrapped at 78 characters. This happens when docs body contains
several consecutive 'inline' elements generated by doxygen.
Solution: Take into account the current column offset of the last line,
and prepend some padding before doc_wrap().
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.
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: 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
- vim.diagnostic.config() now accepts a function for the virtual_text.prefix
option, which allows for rendering e.g., diagnostic severities differently.
Problem:
The function name `vim.pretty_print`:
1. is verbose, which partially defeats its purpose as sugar
2. does not draw from existing precedent or any sort of convention
(except external projects like penlight or python?), which reduces
discoverability, and degrades signaling about best practices.
Solution:
- Rename to `vim.print`.
- Change the behavior so that
1. strings are printed without quotes
2. each arg is printed on its own line
3. tables are indented with 2 instead of 4 spaces
- Example:
:lua ='a', 'b', 42, {a=3}
a
b
42
{
a = 3
}
Comparison of alternatives:
- `vim.print`:
- pro: consistent with Lua's `print()`
- pro: aligns with potential `nvim_print` API function which will
replace nvim_echo, nvim_notify, etc.
- con: behaves differently than Lua's `print()`, slightly misleading?
- `vim.echo`:
- pro: `:echo` has similar "pretty print" behavior.
- con: inconsistent with Lua idioms.
- `vim.p`:
- pro: very short, fits with `vim.o`, etc.
- con: not as discoverable as "echo"
- con: less opportunity for `local p = vim.p` because of potential shadowing.
The existing groups, Error, Hint, Info, Warn cover many use cases, but
neglect the occasion where a diagnostic message should communicate a
non-informative (not a Hint or Info) event. DiagnosticOk covers this
with a generic green colorscheme.
Some functions didn't include the `nil` case in the return type
annotation. This corrects those and also adds a Diagnostic class
definition for the diagnostic.get return type
This introduces a `suffix` option to the `virt_text` config in
`vim.diagnostic.config()`. The suffix can either be a string which is appended
to the diagnostic message or a function returning such. The function receives a
`diagnostic` argument, which is the diagnostic table of the last diagnostic (the
one whose message is rendered as virt text).
Closes#18687
This introduces a `suffix` option to `vim.diagnostic.open_float()` (and
consequently `vim.diagnostic.config()`) that appends some text to each
diagnostic in the float.
It accepts the same types as `prefix`. For multiline diagnostics, the suffix is
only appended to the last line. By default, the suffix will render the
diagnostic error code, if any.
Problem:
The {foo} parameters listed in `:help api` and similar generated docs,
are intended to be a "list" but they aren't prefixed with a list symbol.
This prevents parsers from understanding the list, which forces
generators like `gen_help_html.lua` to use hard-wrapped/preformatted
layout instead of a soft-wrapped "flow" layout.
Solution:
Modify gen_vimdoc.py to prefix {foo} parameters with a "•" symbol.
This will check if the string after the variable in a @param is either
"number", "string", "table", "boolean" and "function" and if so add a
parenthesis around it. This will help separate the variable type with
the following text. Had all our functions been annotated with emmylua
then a more robust solution might have been preferable (such as always
assuming the third string is parameter type without making any checks).
I believe however this is a clear improvement over the current situation
and will suffice for now.
The `prefix_source` function only evaluates the sources from the
diagnostics passed to it; however, because each namespace draws its own
virtual text, its diagnostics will never contain more than a single
source (by definition). This requires changing the semantics of what
"if_many" means from "multiple sources in a single 'batch' of
diagnostics" to "multiple sources of all diagnostics within a buffer".
The overwhelming majority of use cases for `open_float` are to view
diagnostics from the current buffer in a floating window. Thus, most use
cases will just `0` or `nil` as the first argument, which makes the
argument effectively useless and wasteful.
In the cause of optimizing for the primary use case, make the `bufnr`
parameter an optional parameter in the options table. This still allows
using an alternative buffer for those that wish to do so, but makes the
"primary" use case much easier.
The old signature is preserved for backward compatibility, though it can
likely be fully deprecated at some point.
This allows users to hook into diagnostic events with finer granularity
(e.g. per-buffer or file).
BREAKING CHANGE: DiagnosticsChanged and LspDiagnosticsChanged user
autocommands are removed.
