feat(lsp): add async option to vim.lsp.buf.format (#18322)

Deprecates the existing `vim.lsp.buf.formatting` function.
With this, `vim.lsp.buf.format` will replace all three:

- vim.lsp.buf.formatting
- vim.lsp.buf.formatting_sync
- vim.lsp.buf.formatting_seq_sync

1 files changed, 5 insertions, 3 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index d5ee959c36..f55c959a03 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1060,9 +1060,8 @@ format({options})                                       *vim.lsp.buf.format()*
                 See also: ~
                     https://microsoft.github.io/language-server-protocol/specification#textDocument_formatting
                     • timeout_ms (integer|nil, default 1000): Time in
-                      milliseconds to block for formatting requests.
-                      Formatting requests are current synchronous to prevent
-                      editing of the buffer.
+                      milliseconds to block for formatting requests. No effect
+                      if async=true
                     • bufnr (number|nil): Restrict formatting to the clients
                       attached to the given buffer, defaults to the current
                       buffer (0).
@@ -1081,6 +1080,9 @@ format({options})                                       *vim.lsp.buf.format()*
                           end
                         }
 <
+                    • async boolean|nil If true the method won't block.
+                      Defaults to false. Editing the buffer while formatting
+                      asynchronous can lead to unexpected changes.
                     • id (number|nil): Restrict formatting to the client with
                       ID (client.id) matching this field.
                     • name (string|nil): Restrict formatting to the client