docs: news, lsp autocomplete #33047

9 files changed, 51 insertions, 56 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 2ba464e80c..04d24e7a92 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -5805,7 +5805,9 @@ log10({expr})                                                          *log10()*
 
 luaeval({expr} [, {expr}])                                           *luaeval()*
 		Evaluate Lua expression {expr} and return its result converted
-		to Vim data structures. See |lua-eval| for more details.
+		to Vim data structures. See |lua-eval| for details.
+
+		See also |v:lua-call|.
 
                 Parameters: ~
                   • {expr} (`string`)
diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index a68d94828b..0815c64c93 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -791,14 +791,11 @@ Variables:
 To use Nvim as a manpager: >bash
     export MANPAGER='nvim +Man!'
 
-Note that when running `man` from the shell and with that `MANPAGER` in your
-environment, `man` will pre-format the manpage using `groff`. Thus, Nvim
-will inevitably display the manual page as it was passed to it from stdin. One
-of the caveats of this is that the width will _always_ be hard-wrapped and not
-soft wrapped as with `g:man_hardwrap=0`. You can set in your environment: >bash
-    export MANWIDTH=999
-
-So `groff`'s pre-formatting output will be the same as with `g:man_hardwrap=0` i.e soft-wrapped.
+Note: when running `man` from the shell with Nvim as `$MANPAGER`, `man` will
+pre-format the manpage using `groff`, and Nvim will display the manual page as
+it was received from stdin (it can't "undo" the hard-wrap caused by
+man/groff). To prevent man/groff from hard-wrapping the manpage, you can set
+`$MANWIDTH=999` in your environment.
 
 To disable bold highlighting: >vim
     :highlight link manBold Normal
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 780712df6c..bce2f574ae 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -64,6 +64,8 @@ Stop or detach the current UI
                 the channel to be closed, it may be (incorrectly) reported as
                 an error.
 
+                Note: Not supported on Windows, currently.
+
 ------------------------------------------------------------------------------
 GUI commands
 
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index a6cd10afa3..e77ad5dcf3 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -201,6 +201,10 @@ Example: Enable auto-completion and auto-formatting ("linting"): >lua
 
         -- Enable auto-completion. Note: Use CTRL-Y to select an item. |complete_CTRL-Y|
         if client:supports_method('textDocument/completion') then
+          -- Optional: trigger autocompletion on EVERY keypress. May be slow!
+          -- local chars = {}; for i = 32, 126 do table.insert(chars, string.char(i)) end
+          -- client.server_capabilities.completionProvider.triggerCharacters = chars
+
           vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true})
         end
 
@@ -1881,12 +1885,27 @@ Example: activate LSP-driven auto-completion: >lua
     })
 <
 
+                                                          *lsp-autocompletion*
+
+The LSP `triggerCharacters` field decides when to trigger autocompletion. If
+you want to trigger on EVERY keypress you can either:
+• Extend `client.server_capabilities.completionProvider.triggerCharacters` on
+  `LspAttach`, before you call
+  `vim.lsp.completion.enable(… {autotrigger=true})`. See the |lsp-attach|
+  example.
+• Call `vim.lsp.completion.get()` from the handler described at
+  |compl-autocomplete|.
+
 
                                                  *vim.lsp.completion.enable()*
 enable({enable}, {client_id}, {bufnr}, {opts})
     Enables or disables completions from the given language client in the
     given buffer. Example: |lsp-attach| |lsp-completion|
 
+    Note: the behavior of `autotrigger=true` is controlled by the LSP
+    `triggerCharacters` field. You can override it on LspAttach, see
+    |lsp-autocompletion|.
+
     Parameters: ~
       • {enable}     (`boolean`) True to enable, false to disable
       • {client_id}  (`integer`) Client ID
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 86cfc56693..feaf78f314 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -435,18 +435,12 @@ where the args are converted to Lua values. The expression >vim
 is equivalent to the Lua chunk >lua
     return somemod.func(...)
 
-In addition, functions of packages can be accessed like >vim
+Lua module functions can be accessed like: >vim
     call v:lua.require'mypack'.func(arg1, arg2)
     call v:lua.require'mypack.submod'.func(arg1, arg2)
 Note: Only single quote form without parens is allowed. Using
-`require"mypack"` or `require('mypack')` as prefixes do NOT work (the latter
-is still valid as a function call of itself, in case require returns a useful
-value).
+`require"mypack"` or `require('mypack')` as a prefix does NOT work.
 
-The `v:lua` prefix may be used to call Lua functions as |method|s. For
-example: >vim
-    :eval arg1->v:lua.somemod.func(arg2)
-<
 You can use `v:lua` in "func" options like 'tagfunc', 'omnifunc', etc.
 For example consider the following Lua omnifunc handler: >lua
 
@@ -457,11 +451,13 @@ For example consider the following Lua omnifunc handler: >lua
         return {'stuff', 'steam', 'strange things'}
       end
     end
+    -- Note: The module ("mymod") must be a Lua global, or use require() as
+    -- shown above to access it from a package.
     vim.bo[buf].omnifunc = 'v:lua.mymod.omnifunc'
 
-Note: The module ("mymod" in the above example) must either be a Lua global,
-or use require() as shown above to access it from a package.
-
+You can also use `v:lua` to call Lua functions as Vimscript |method|s: >vim
+    :eval arg1->v:lua.somemod.func(arg2)
+<
 Note: `v:lua` without a call is not allowed in a Vimscript expression:
 |Funcref|s cannot represent Lua functions. The following are errors: >vim
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index a0a7fa0dee..f32e963103 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -11,39 +11,6 @@ For changes in the previous release, see |news-0.10|.
                                        Type |gO| to see the table of contents.
 
 ==============================================================================
-BREAKING CHANGES IN HEAD OR EXPERIMENTAL                    *news-breaking-dev*
-
-              ====== Remove this section before release. ======
-
-The following changes to UNRELEASED features were made during the development
-cycle (Nvim HEAD, the "master" branch).
-
-EXPERIMENTS
-
-• Removed `vim.loader.disable()`. Use `vim.loader.enable(false)` instead.
-
-LSP
-
-• `lsp/` runtimepath files should return a table instead of calling
-  |vim.lsp.config()| (or assigning to `vim.lsp.config`). See |lsp-config|
-• `vim.lsp.buf.document_symbol()` uses the |location-list| by default. Use
-  `vim.lsp.buf.document_symbol({ loclist = false })` to use the |quickfix|
-  list.
-• `vim.lsp.completion.trigger()` has been renamed to
-  |vim.lsp.completion.get()|.
-
-OPTIONS
-
-• 'jumpoptions' flag "unload" has been renamed to "clean".
-• The `msghistory` option has been removed in favor of 'messagesopt'.
-
-TREESITTER
-
-• *TSNode:child_containing_descendant()* has been removed in the tree-sitter
-  library and is no longer available; use |TSNode:child_with_descendant()|
-  instead.
-
-==============================================================================
 BREAKING CHANGES                                                *news-breaking*
 
 These changes may require adaptations in your config or plugins.
@@ -266,7 +233,6 @@ DIAGNOSTICS
 
 EDITOR
 
-• Use |g==| in :help docs to execute Lua and Vimscript code examples.
 • Improved |paste| handling for redo (dot-repeat) and macros (|recording|):
   • Redoing a large paste is significantly faster and ignores 'autoindent'.
   • Replaying a macro with |@| also replays pasted text.
diff --git a/runtime/lua/vim/lsp/completion.lua b/runtime/lua/vim/lsp/completion.lua
index 9345cb8d83..4f16d4173a 100644
--- a/runtime/lua/vim/lsp/completion.lua
+++ b/runtime/lua/vim/lsp/completion.lua
@@ -22,6 +22,14 @@
 ---   end,
 --- })
 --- ```
+---
+--- [lsp-autocompletion]()
+---
+--- The LSP `triggerCharacters` field decides when to trigger autocompletion. If you want to trigger
+--- on EVERY keypress you can either:
+--- - Extend `client.server_capabilities.completionProvider.triggerCharacters` on `LspAttach`,
+---   before you call `vim.lsp.completion.enable(… {autotrigger=true})`. See the |lsp-attach| example.
+--- - Call `vim.lsp.completion.get()` from the handler described at |compl-autocomplete|.
 
 local M = {}
 
@@ -781,6 +789,9 @@ end
 --- Enables or disables completions from the given language client in the given buffer.
 --- Example: |lsp-attach| |lsp-completion|
 ---
+--- Note: the behavior of `autotrigger=true` is controlled by the LSP `triggerCharacters` field. You
+--- can override it on LspAttach, see |lsp-autocompletion|.
+---
 --- @param enable boolean True to enable, false to disable
 --- @param client_id integer Client ID
 --- @param bufnr integer Buffer handle, or 0 for the current buffer
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index d29c96a763..8ca1868ff1 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -6494,7 +6494,9 @@ M.funcs = {
     base = 1,
     desc = [=[
       Evaluate Lua expression {expr} and return its result converted
-      to Vim data structures. See |lua-eval| for more details.
+      to Vim data structures. See |lua-eval| for details.
+
+      See also |v:lua-call|.
 
     ]=],
     lua = false,
diff --git a/src/nvim/msgpack_rpc/channel.c b/src/nvim/msgpack_rpc/channel.c
index fe480fff45..19aab7e317 100644
--- a/src/nvim/msgpack_rpc/channel.c
+++ b/src/nvim/msgpack_rpc/channel.c
@@ -518,7 +518,7 @@ void rpc_free(Channel *channel)
   api_free_dict(channel->rpc.info);
 }
 
-/// Logs a fatal error received from a channel, then closes the channel.
+/// Closes a channel after receiving fatal error, and logs a message.
 static void chan_close_on_err(Channel *channel, char *msg, int loglevel)
 {
   for (size_t i = 0; i < kv_size(channel->rpc.call_stack); i++) {