LSP: Expose diagnostics grouped by bufnr (#11932)

Expose `vim.lsp.buf.diagnostics_by_buf`

This makes it easier to customize the diagnostics behavior. For example
to defer the update they can override the
`textDocument/publishDiagnostics` callback to only call
`buf_diagnostics_save_positions` and then defer the other actions to a
autocmd event.

1 files changed, 22 insertions, 2 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 4c59e53343..c7baec0491 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -915,6 +915,21 @@ apply_text_edits({text_edits}, {bufnr})
 apply_workspace_edit({workspace_edit})
                 TODO: Documentation
 
+                                         *vim.lsp.util.diagnostics_by_buf*
+diagnostics_by_buf
+                A table containing diagnostics grouped by buf.
+
+                {<bufnr>: {diagnostics}}
+
+		{diagnostics} is an array of diagnostics.
+
+                By default this is populated by the
+                `textDocument/publishDiagnostics` callback via
+                |vim.lsp.util.buf_diagnostics_save_positions|.
+
+                It contains entries for active buffers. Once a buffer is
+                detached the entries for it are discarded.
+
 buf_clear_diagnostics({bufnr})          *vim.lsp.util.buf_clear_diagnostics()*
                 TODO: Documentation
  
@@ -945,9 +960,14 @@ buf_diagnostics_count({kind})
 buf_clear_references({bufnr})            *vim.lsp.util.buf_clear_references()*
                 TODO: Documentation
 
-                               *vim.lsp.util.buf_diagnostics_save_positions()*
+                                        *vim.lsp.util.buf_diagnostics_save()*
 buf_diagnostics_save_positions({bufnr}, {diagnostics})
-                TODO: Documentation
+                Stores the diagnostics into |vim.lsp.util.diagnostics_by_buf|
+
+                Parameters: ~
+                    {bufr}         bufnr for which the diagnostics are for.
+                    {diagnostics}  Diagnostics[] received from the
+                                   langauge server.
 
                                     *vim.lsp.util.buf_diagnostics_underline()*
 buf_diagnostics_underline({bufnr}, {diagnostics})