From 3d13807b8d627c2d4354e8456108dd5a3f01d7c8 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 7 Sep 2025 22:49:21 -0400 Subject: [PATCH] docs: backport (#35675) docs: lsp, misc --- runtime/doc/api.txt | 6 +++--- runtime/doc/change.txt | 32 ++++++++++++++++---------------- runtime/doc/develop.txt | 4 +++- runtime/doc/lua-guide.txt | 6 +++--- runtime/doc/lua-plugin.txt | 22 +++++++++++++--------- scripts/cliff.toml | 4 ++-- scripts/release.sh | 2 +- src/gen/gen_help_html.lua | 2 ++ src/nvim/README.md | 7 ++++++- src/nvim/api/vim.c | 2 +- 10 files changed, 50 insertions(+), 37 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 3ff1d67733..9c583799fe 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1319,9 +1319,9 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) debugging and orchestration. (Note: Something is better than nothing! Fields are optional, but at least set `name`.) - Can be called more than once; the caller should merge old info if - appropriate. Example: library first identifies the channel, then a plugin - using that library later identifies itself. + Can be called more than once; caller should merge old info if appropriate. + Example: a library first identifies the channel, then a plugin using that + library later identifies itself. Attributes: ~ |RPC| only diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index f7cbf7fd36..8a2ac14a73 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1143,23 +1143,23 @@ first word). You can use the "']" or "`]" command after the put command to move the cursor to the end of the inserted text, or use "'[" or "`[" to move the cursor to the start. - *put-Visual-mode* *v_p* *v_P* + *put-Visual-mode* When using a put command like |p| or |P| in Visual mode, Vim will try to -replace the selected text with the contents of the register. Whether this -works well depends on the type of selection and the type of the text in the -register. With blockwise selection it also depends on the size of the block -and whether the corners are on an existing character. (Implementation detail: -it actually works by first putting the register after the selection and then -deleting the selection.) -With |p| the previously selected text is put in the unnamed register (and -possibly the selection and/or clipboard). This is useful if you want to put -that text somewhere else. But you cannot repeat the same change. -With |P| the unnamed register is not changed (and neither the selection or -clipboard), you can repeat the same change. But the deleted text cannot be -used. If you do need it you can use |p| with another register. E.g., yank -the text to copy, Visually select the text to replace and use "0p . You can -repeat this as many times as you like, and the unnamed register will be -changed each time. +replace the selected text with the contents of the register. How this +works depends on the type of selection and the text. With blockwise selection +it also depends on the size of the block and whether the corners are on an +existing character. (Implementation detail: it actually works by first +putting the register after the selection and then deleting the selection.) + *v_p* +|p| in Visual mode puts text and sets the default register (unnamed, +selection, or clipboard) to the previously-selected text. Useful if you want +to put that text somewhere else. But you cannot repeat the same change. + *v_P* +|P| in Visual mode puts text without setting the default register. You can +repeat the change, but the deleted text cannot be used. If you do need it you +can use |p| with another register. E.g., yank the text to copy, Visually +select the text to replace and use "0p . You can repeat this as many times as +you like, and the unnamed register will be changed each time. *blockwise-put* When a register contains text from one line (characterwise), using a blockwise Visual selection, putting that register will paste that text diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index d649fa5812..17bc21c2ea 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -446,6 +446,8 @@ Use existing common {verb} names (actions) if possible: - is_enabled: Checks if functionality is enabled. - open: Opens something (a buffer, window, …) - parse: Parses something into a structured form + - request: Calls a remote (network, RPC) operation. + - send: Writes data or a message to a channel. - set: Sets a thing (or group of things) - start: Spin up a long-lived process. Prefer "enable" except when "start" is obviously more appropriate. @@ -456,7 +458,7 @@ Do NOT use these deprecated verbs: - contains: Prefer "has". - disable: Prefer `enable(enable: boolean)`. - exit: Prefer "cancel" (or "stop" if appropriate). - - is_disabled: Prefer `is_enabled()`. + - is_disabled: Prefer `!is_enabled()`. - list: Redundant with "get" - notify: Redundant with "print", "echo" - show: Redundant with "print", "echo" diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index 9d37b599e6..285e202a50 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -10,9 +10,9 @@ ============================================================================== Introduction *lua-guide* -This guide introduces the basics of everyday usage of Lua to configure and -operate Nvim. It assumes some familiarity with the (non-Lua) basics of Nvim -(commands, options, mappings, autocommands), which are covered in the +This guide introduces the basics of everyday Lua usage for configuring and +controlling Nvim. It assumes some familiarity with the (non-Lua) basics of +Nvim (commands, options, mappings, autocommands), which are covered in the |user-manual|. This is not a comprehensive encyclopedia of all available features. Think of diff --git a/runtime/doc/lua-plugin.txt b/runtime/doc/lua-plugin.txt index dc715f7223..25eba20c93 100644 --- a/runtime/doc/lua-plugin.txt +++ b/runtime/doc/lua-plugin.txt @@ -10,7 +10,7 @@ ============================================================================== Introduction *lua-plugin* -This document provides guidance for developing Nvim (Lua) plugins: +This document provides guidance for developing Nvim Lua plugins. See |lua-guide| for guidance on using Lua to configure and operate Nvim. See |luaref| and |lua-concepts| for details on the Lua programming language. @@ -19,7 +19,7 @@ See |luaref| and |lua-concepts| for details on the Lua programming language. Creating your first plugin *lua-plugin-new* Any Vimscript or Lua code file that lives in the right directory, -automatically is a "plugin". There's no maniest or "registration" required. +automatically is a "plugin". There's no manifest or "registration" step. You can try it right now: @@ -35,7 +35,7 @@ You can try it right now: Besides `plugin/foo.lua`, which is always run at startup, you can define Lua modules in the `lua/` directory. Those modules aren't loaded until your -`plugin/foo.lua`, the user, calls `require(…)`. +`plugin/foo.lua`, or the user, calls `require(…)`. ============================================================================== Type safety *lua-plugin-type-safety* @@ -108,11 +108,11 @@ In your plugin: >lua vim.keymap.set('n', '(SayHello)', function() print('Hello from normal mode') - end, { noremap = true }) + end) vim.keymap.set('v', '(SayHello)', function() print('Hello from visual mode') - end, { noremap = true }) + end) < In the user's config: >lua @@ -182,7 +182,9 @@ For example, instead of: local foo = require('foo') vim.api.nvim_create_user_command('MyCommand', function() foo.do_something() - end, { -- ... }) + end, { + -- ... + }) < which calls `require('foo')` as soon as the module is loaded, you can lazy-load it by moving the `require` into the command's implementation: @@ -233,7 +235,7 @@ A plugin tailored to Rust development might have initialization in -- e.g. add a || mapping or create a command vim.keymap.set('n', '(MyPluginBufferAction)', function() print('Hello') - end, { noremap = true, buffer = bufnr, }) + end, { buffer = bufnr, }) < ============================================================================== Configuration *lua-plugin-config* @@ -277,7 +279,7 @@ Versioning and releases *lua-plugin-versioning* Consider: - Use |vim.deprecate()| or a `---@deprecate` annotation when you need to - communicate a (future) breaking change or discourged practice. + communicate a (future) breaking change or discouraged practice. - Using SemVer https://semver.org/ tags and releases to properly communicate bug fixes, new features, and breaking changes. - Automating versioning and releases in CI. @@ -302,7 +304,9 @@ VERSIONING TOOLS Documentation *lua-plugin-doc* Provide vimdoc (see |help-writing|), so that users can read your plugin's -documentation in Nvim, by entering `:h {plugin}` in |command-mode|. +documentation in Nvim, by entering `:h {plugin}` in |command-mode|. The +help-tags (the right-aligned "search keywords" in the help documents) are +regenerated using the |:helptags| command. DOCUMENTATION TOOLS diff --git a/scripts/cliff.toml b/scripts/cliff.toml index 51725cacfc..2e495460db 100644 --- a/scripts/cliff.toml +++ b/scripts/cliff.toml @@ -4,8 +4,8 @@ # changelog header header = """ # Changelog\n -For notable changes, see runtime/doc/news.txt (or `:help news` in Nvim).\n -Following is a list of fixes/features commits.\n +Following is a list of commits (fixes/features only) in this release.\n +See `:help news` in Nvim for release notes.\n """ # template for the changelog body # https://github.com/Keats/tera diff --git a/scripts/release.sh b/scripts/release.sh index b461c9ea50..5a340cc340 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -97,5 +97,5 @@ echo " Next steps: - Run tests/CI (version_spec.lua)! - Push the tag: - git push --follow-tags + git push v${__VERSION} - Update website: index.html" diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua index 446cba39f4..848f3b15c5 100644 --- a/src/gen/gen_help_html.lua +++ b/src/gen/gen_help_html.lua @@ -72,6 +72,8 @@ local new_layout = { ['gui.txt'] = true, ['intro.txt'] = true, ['lua.txt'] = true, + ['lua-guide.txt'] = true, + ['lua-plugin.txt'] = true, ['luaref.txt'] = true, ['news.txt'] = true, ['news-0.9.txt'] = true, diff --git a/src/nvim/README.md b/src/nvim/README.md index 9ef39cc90f..6abc56ad1f 100644 --- a/src/nvim/README.md +++ b/src/nvim/README.md @@ -409,13 +409,18 @@ name, etc. All the global variables are declared in `globals.h`. -### The main loop +### The main event-loop The main loop is implemented in state_enter. The basic idea is that Vim waits for the user to type a character and processes it until another character is needed. Thus there are several places where Vim waits for a character to be typed. The `vgetc()` function is used for this. It also handles mapping. +What we consider the "Nvim event loop" is actually a wrapper around `uv_run` to +handle both the `fast_events` queue and possibly (a suitable subset of) deferred +events. Therefore "raw" `vim.uv.run()` is often not enough to "yield" from Lua +plugins; instead they can call `vim.wait(0)`. + Updating the screen is mostly postponed until a command or a sequence of commands has finished. The work is done by `update_screen()`, which calls `win_update()` for every window, which calls `win_line()` for every line. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index f3c0286eb6..9e99db8d32 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -1489,7 +1489,7 @@ Array nvim_get_api_info(uint64_t channel_id, Arena *arena) /// orchestration. (Note: Something is better than nothing! Fields are optional, but at least set /// `name`.) /// -/// Can be called more than once; the caller should merge old info if appropriate. Example: library +/// Can be called more than once; caller should merge old info if appropriate. Example: a library /// first identifies the channel, then a plugin using that library later identifies itself. /// /// @param channel_id