lsp: validate and document server settings (#13698)

* update lua documentation
* run docgen

3 files changed, 59 insertions, 15 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 193593be13..772afdcc1a 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -639,8 +639,9 @@ client()                                                      *vim.lsp.client*
                     automatically escalate and force shutdown.
                   • is_stopped() Checks whether a client is stopped. Returns:
                     true if the client is fully stopped.
-                  • on_attach(client, bufnr) Runs the on_attach function from the
-                    client's config if it was defined. Useful for buffer-local setup.
+                  • on_attach(client, bufnr) Runs the on_attach function from
+                    the client's config if it was defined. Useful for
+                    buffer-local setup.
 
                 • Members
                   • {id} (number): The id allocated to the client.
@@ -776,8 +777,9 @@ start_client({config})                                *vim.lsp.start_client()*
                     {handlers}         Map of language server method names to
                                        |lsp-handler|
                     {settings}         Map with language server specific
-                                       settings. These are returned to the language server if
-                                       requested via `workspace/configuration`. Keys are
+                                       settings. These are returned to the
+                                       language server if requested via
+                                       `workspace/configuration` . Keys are
                                        case-sensitive.
                     {init_options}     Values to pass in the initialization
                                        request as `initializationOptions` .
@@ -815,7 +817,14 @@ start_client({config})                                *vim.lsp.start_client()*
                                        `capabilities.offsetEncoding` was sent
                                        to it. You can only modify the
                                        `client.offset_encoding` here before
-                                       any notifications are sent.
+                                       any notifications are sent. Most
+                                       language servers expect to be sent
+                                       client specified settings after
+                                       initialization. Neovim does not make
+                                       this assumption. A
+                                       `workspace/didChangeConfiguration`
+                                       notification should be sent to the
+                                       server during on_init.
                     {on_exit}          Callback (code, signal, client_id)
                                        invoked on client exit.
                                        • code: exit code of the process
@@ -1342,6 +1351,10 @@ set_signs({diagnostics}, {bufnr}, {client_id}, {sign_ns}, {opts})
                     {sign_ns}      number|nil
                     {opts}         table Configuration for signs. Keys:
                                    • priority: Set the priority of the signs.
+                                   • severity_limit (DiagnosticSeverity):
+                                     • Limit severity of diagnostics found.
+                                       E.g. "Warning" means { "Error",
+                                       "Warning" } will be valid.
 
                                           *vim.lsp.diagnostic.set_underline()*
 set_underline({diagnostics}, {bufnr}, {client_id}, {diagnostic_ns}, {opts})
@@ -1420,7 +1433,16 @@ show_line_diagnostics({opts}, {bufnr}, {line_nr}, {client_id})
                     {client_id}  number|nil the client id
 
                 Return: ~
-                    {popup_bufnr, win_id}
+                    table {popup_bufnr, win_id}
+
+
+==============================================================================
+Lua module: vim.lsp.handlers                                    *lsp-handlers*
+
+                                        *vim.lsp.handlers.progress_callback()*
+progress_callback({_}, {_}, {params}, {client_id})
+                See also: ~
+                    https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand
 
 
 ==============================================================================
@@ -1615,6 +1637,9 @@ get_effective_tabstop({bufnr})          *vim.lsp.util.get_effective_tabstop()*
                 See also: ~
                     |softtabstop|
 
+get_progress_messages()                 *vim.lsp.util.get_progress_messages()*
+                TODO: Documentation
+
 jump_to_location({location})                 *vim.lsp.util.jump_to_location()*
                 Jumps to a location.
 
@@ -1636,6 +1661,19 @@ locations_to_items({locations})            *vim.lsp.util.locations_to_items()*
                 Return: ~
                     (table) list of items
 
+lookup_section({settings}, {section})          *vim.lsp.util.lookup_section()*
+                Helper function to return nested values in language server
+                settings
+
+                Parameters: ~
+                    {settings}  a table of language server settings
+                    {section}   a string indicating the field of the settings
+                                table
+
+                Return: ~
+                    (table or string) The value of settings accessed via
+                    section
+
                                   *vim.lsp.util.make_floating_popup_options()*
 make_floating_popup_options({width}, {height}, {opts})
                 Creates a table with sensible default options for a floating
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 92898cfad1..0bbed56662 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1265,14 +1265,12 @@ validate({opt})                                               *vim.validate()*
 
                   vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
                      => NOP (success)
-<
->
-    vim.validate{arg1={1, 'table'}}
-       => error('arg1: expected table, got number')
-<
->
-    vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
-       => error('arg1: expected even number, got 3')
+
+                  vim.validate{arg1={1, 'table'}}
+                     => error('arg1: expected table, got number')
+
+                  vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
+                     => error('arg1: expected even number, got 3')
 <
 
                 Parameters: ~
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index 27fc4a2ab5..d20d39b824 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -226,6 +226,7 @@ local function validate_client_config(config)
     on_error        = { config.on_error, "f", true };
     on_exit         = { config.on_exit, "f", true };
     on_init         = { config.on_init, "f", true };
+    settings        = { config.settings, "t", true };
     before_init     = { config.before_init, "f", true };
     offset_encoding = { config.offset_encoding, "s", true };
     flags           = { config.flags, "t", true };
@@ -400,6 +401,10 @@ end
 ---
 --@param handlers Map of language server method names to |lsp-handler|
 ---
+--@param settings Map with language server specific settings. These are
+--- returned to the language server if requested via `workspace/configuration`.
+--- Keys are case-sensitive.
+---
 --@param init_options Values to pass in the initialization request
 --- as `initializationOptions`. See `initialize` in the LSP spec.
 ---
@@ -426,7 +431,10 @@ end
 --- the server may send. For example, clangd sends
 --- `initialize_result.offsetEncoding` if `capabilities.offsetEncoding` was
 --- sent to it. You can only modify the `client.offset_encoding` here before
---- any notifications are sent.
+--- any notifications are sent. Most language servers expect to be sent client specified settings after
+--- initialization. Neovim does not make this assumption. A
+--- `workspace/didChangeConfiguration` notification should be sent
+---  to the server during on_init.
 ---
 --@param on_exit Callback (code, signal, client_id) invoked on client
 --- exit.