reverts e0d92b9cc2#28502
Problem:
`vim.ui.open()` has a `pcall()` like signature, under the assumption
that this is the Lua idiom for returning result-or-error. However, the
`result|nil, errmsg|nil` pattern:
- has precedent in:
- `io.open`
- `vim.uv` (`:help luv-error-handling`)
- has these advantages:
- Can be used with `assert()`:
```
local result, err = assert(foobar())
```
- Allows LuaLS to infer the type of `result`:
```
local result, err = foobar()
if err then
...
elseif result then
...
end
```
Solution:
- Revert to the `result|nil, errmsg|nil` pattern.
- Document the pattern in our guidelines.
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.
Recommend adding a space after i.e. `--- @see`.
The "space" variant is common for the vast majority of docstring formats
such as doxygen, javadoc and typescript.
* 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>
Enforce consistent terminology (defined in
`gen_help_html.lua:spell_dict`) for common misspellings.
This does not spellcheck English in general (perhaps a future TODO,
though it may be noisy).
Co-authored by: zeertzjq <zeertzjq@outlook.com>
Co-authored by: Steven Todd McIntyre II <114119064+stmii@users.noreply.github.com>
Co-authored by: nobe4 <nobe4@users.noreply.github.com>
- docs: mention --luadev-mod to run with lua runtime files
When changing a lua file in the ./runtime folder, a new contributor
might expect changes to be applied to the built Neovim binary.
- Improve generated HTML by updating parser which includes fixes for
single "'" and single "|":
https://github.com/neovim/tree-sitter-vimdoc/pull/31
- Updated parser also fixes the conceal issue for "help" highlight
queries https://github.com/neovim/tree-sitter-vimdoc/issues/23 by
NOT including whitespace in nodes.
- But this means we need to restore the getws() function which scrapes
leading whitespace from the original input (buffer).
Co-authored-by: Sean Dewar <seandewar@users.noreply.github.com>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: Sebastian Volland <seb@baunz.net>
Co-authored-by: Lewis Russell <lewis6991@gmail.com>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>
Analogous to nodejs's `on('data', …)` interface, here on_key is the "add
listener" interface.
ref 3ccdbc570d#12536
BREAKING_CHANGE: vim.register_keystroke_callback() is now an error.
The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.
Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.
- We already find ourselves renaming nvim_execute_lua in tests and
scripts, which suggests "exec" is the verb we actually want.
- Add "exec" verb to `:help dev-api`.
Instead of deciding provider status in eval_has_provider, move the
decision to the provider Vim scripts.
Previously, provider loading worked as follows:
1. eval_has_provider() verified provider availability by searching for
the provider#providername#Call function and cached this verificaion as a static
variable for some providers
2. providers short-circuited on loading to prevent the definition of the
Call function (with the exception of the node provider that did not)
This commit changes the expected interface between nvim and its
providers to facilitate provider reloading, by splitting the
verification of the provider from the availability of the Call function.
eval_has_provider() now checks for a provider#providername#enabled
variable. It is up to the provider script to set this to 0 or 1
accordingly. eval_call_provider() remains unchanged.
All providers hosting a Call function were updated to respect this.
The clipboard provider now has a Reload function to reload the
provider.
