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: `vim.deprecate()` can be relatively significantly slower than
the deprecated function in "Nvim" plugin.
Solution: Optimize checks for "Nvim" plugin. This also results into not
distinguishing "xxx-dev" and "xxx" versions when doing checks, which
is essentially covered by the deprecation logic itself.
With this rewrite I get the times from #28459: `{ 0.024827, 0.003797, 0.002024, 0.001774, 0.001703 }`.
For quicker reference:
- On current Nightly it is something like `{ 3.72243, 0.918169, 0.968143, 0.763256, 0.783424 }`.
- On 0.9.5: `{ 0.002955, 0.000361, 0.000281, 0.000251, 0.00019 }`.
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.ui.open "locks up" Nvim if the spawned process does not terminate. #27986
Solution:
- Change `vim.ui.open()`:
- Do not call `wait()`.
- Return a `SystemObj`. The caller can decide if it wants to `wait()`.
- Change `gx` to `wait()` only a short time.
- Allows `gx` to show a message if the command fails, without the
risk of waiting forever.
- 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).
Problem:
On devel(nightly) versions, deprecation warnings for hard-deprecated
features are not being displayed. E.g.,
- to be removed in: 0.11
- hard-deprecation since 0.10
- soft-deprecation since 0.9
then 0.10-nightly (0.10.0-dev) versions as well as 0.10.0 (stable)
should display the deprecation warning message.
Solution:
Improve the code and logic on `vim.deprecate()`, and improve
test cases with mocked `vim.version()`.
As specified by MAINTAIN.md, features should be soft deprecated at first
(meaning no warnings) to give people a chance to adjust. The problem
with this approach is that deprecating a feature becomes harder than
usual as during the soft deprecation period you need to remember not to
issue a warning, and during the hard deprecation period you need to
remember to start issuing a warning.
This behavior is only enforced if the `plugin` parameter is `nil` as
plugins may not want this specific behavior.
Problem:
The swapfile "E325: ATTENTION" dialog is displayed when editing a file
already open in another (running) Nvim. Usually this behavior is
annoying and irrelevant:
- "Recover" and the other options ("Open readonly", "Quit", "Abort") are
almost never wanted.
- swapfiles are less relevant for "multi-Nvim" since 'autoread' is
enabled by default.
- Even less relevant if user enables 'autowrite'.
Solution:
Define a default SwapExists handler which does the following:
1. If the swapfile is owned by a running Nvim process, automatically
chooses "(E)dit anyway" (caveat: this creates a new, extra swapfile,
which is mostly harmless and ignored except by `:recover` or `nvim -r`.
2. Shows a 1-line "ignoring swapfile..." message.
3. Users can disable the default SwapExists handler via `autocmd! nvim_swapfile`.
- Remove the usage of the term "defer" to avoid confusion with
`vim.defer_fn`, which also calls `vim.schedule_wrap` internally.
- Explicitly state that `vim.schedule_wrap` returns a function in the
text.
- Mention that arguments are passed along.
- Include a usage example.
- Rename param to `fn`.
Memoizes a function, using a custom function to hash the arguments.
Private for now until:
- There are other places in the codebase that could benefit from this
(e.g. LSP), but might require other changes to accommodate.
- Invalidation of the cache needs to be controllable. Using weak tables
is an acceptable invalidation policy, but it shouldn't be the only
one.
- I don't think the story around `hash_fn` is completely thought out. We
may be able to have a good default hash_fn by hashing each argument,
so basically a better 'concat'.
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
Problem: Using nvim_feedkeys in default mappings makes it hard to use
them as a part of another mapping.
Solution: Use an expression mapping and stop Visual mode later.
Fix#24518.
Problem:
netrw may conflict with the Nvim default "gx" mapping.
Solution:
Initialize keymapping earlier by moving it to vim._init_default_mappings().
That also avoids needing to check maparg().
* 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>
Problem:
The default "#" mapping fails on the following example after v$h# with
cursor at start of the first line:
aa?/\bb
aa
aa?/\bb
Solution:
Also escape "?".
