Merge remote-tracking branch 'upstream/master' into aucmd_textputpostaucmd_textputpost

1 files changed, 72 insertions, 47 deletions

diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 7066a3739a..7f5c809ac3 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -40,15 +40,15 @@ requires a namespace.
 
                                                         *diagnostic-structure*
 A diagnostic is a Lua table with the following keys. Required keys are
-indicated with (*):
+indicated with (+):
 
     bufnr: Buffer number
-    lnum(*): The starting line of the diagnostic
+    lnum(+): The starting line of the diagnostic
     end_lnum: The final line of the diagnostic
-    col(*): The starting column of the diagnostic
+    col(+): The starting column of the diagnostic
     end_col: The final column of the diagnostic
     severity: The severity of the diagnostic |vim.diagnostic.severity|
-    message(*): The diagnostic text
+    message(+): The diagnostic text
     source: The source of the diagnostic
     code: The diagnostic code
     user_data: Arbitrary data plugins or users can add
@@ -66,7 +66,7 @@ The "severity" key in a diagnostic is one of the values defined in
     vim.diagnostic.severity.HINT
 
 Functions that take a severity as an optional parameter (e.g.
-|vim.diagnostic.get()|) accept one of two forms:
+|vim.diagnostic.get()|) accept one of three forms:
 
 1. A single |vim.diagnostic.severity| value: >lua
 
@@ -75,8 +75,17 @@ Functions that take a severity as an optional parameter (e.g.
 2. A table with a "min" or "max" key (or both): >lua
 
     vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } })
+<
+    This form allows users to specify a range of severities.
+
+3. A list-like table: >lua
 
-The latter form allows users to specify a range of severities.
+    vim.diagnostic.get(0, { severity = {
+        vim.diagnostic.severity.WARN,
+        vim.diagnostic.severity.INFO,
+    } })
+<
+    This form allows users to filter for specific severities
 
 ==============================================================================
 HANDLERS                                                *diagnostic-handlers*
@@ -295,6 +304,14 @@ DiagnosticSignHint
 DiagnosticSignOk
     Used for "Ok" signs in sign column.
 
+                                                *hl-DiagnosticDeprecated*
+DiagnosticDeprecated
+    Used for deprecated or obsolete code.
+
+                                                *hl-DiagnosticUnnecessary*
+DiagnosticUnnecessary
+    Used for unnecessary or unused code.
+
 ==============================================================================
 SIGNS                                                   *diagnostic-signs*
 
@@ -325,7 +342,7 @@ Example: >lua
     vim.api.nvim_create_autocmd('DiagnosticChanged', {
       callback = function(args)
         local diagnostics = args.data.diagnostics
-        vim.pretty_print(diagnostics)
+        vim.print(diagnostics)
       end,
     })
 <
@@ -342,19 +359,17 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
     followed by namespace configuration, and finally global configuration.
 
     For example, if a user enables virtual text globally with >lua
-
-       vim.diagnostic.config({ virtual_text = true })
+        vim.diagnostic.config({ virtual_text = true })
 <
 
     and a diagnostic producer sets diagnostics with >lua
-
-       vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
+        vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
 <
 
     then virtual text will not be enabled for those diagnostics.
 
-    Note:
-        Each of the configuration options below accepts one of the following:
+    Note: ~
+      • Each of the configuration options below accepts one of the following:
         • `false`: Disable this feature
         • `true`: Enable this feature, use default settings.
         • `table`: Enable this feature with overrides. Use an empty table to
@@ -374,7 +389,10 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
                      • virtual_text: (default true) Use virtual text for
                        diagnostics. If multiple diagnostics are set for a
                        namespace, one prefix per diagnostic + the last
-                       diagnostic message are shown. Options:
+                       diagnostic message are shown. In addition to the
+                       options listed below, the "virt_text" options of
+                       |nvim_buf_set_extmark()| may also be used here (e.g.
+                       "virt_text_pos" and "hl_mode"). Options:
                        • severity: Only show virtual text for diagnostics
                          matching the given severity |diagnostic-severity|
                        • source: (boolean or string) Include the diagnostic
@@ -384,8 +402,14 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
                          always show the diagnostic source.
                        • spacing: (number) Amount of empty spaces inserted at
                          the beginning of the virtual text.
-                       • prefix: (string) Prepend diagnostic message with
-                         prefix.
+                       • prefix: (string or function) prepend diagnostic
+                         message with prefix. If a function, it must have the
+                         signature (diagnostic, i, total) -> string, where
+                         {diagnostic} is of type |diagnostic-structure|, {i}
+                         is the index of the diagnostic being evaluated, and
+                         {total} is the total number of diagnostics for the
+                         line. This can be used to render diagnostic symbols
+                         or error codes.
                        • suffix: (string or function) Append diagnostic
                          message with suffix. If a function, it must have the
                          signature (diagnostic) -> string, where {diagnostic}
@@ -423,32 +447,32 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
                        severities are displayed before lower severities (e.g.
                        ERROR is displayed before WARN). Options:
                        • reverse: (boolean) Reverse sort order
-      • {namespace}  (number|nil) Update the options for the given namespace.
+      • {namespace}  (integer|nil) Update the options for the given namespace.
                      When omitted, update the global diagnostic options.
 
 disable({bufnr}, {namespace})                       *vim.diagnostic.disable()*
     Disable diagnostics in the given buffer.
 
     Parameters: ~
-      • {bufnr}      (number|nil) Buffer number, or 0 for current buffer. When
-                     omitted, disable diagnostics in all buffers.
-      • {namespace}  (number|nil) Only disable diagnostics for the given
+      • {bufnr}      (integer|nil) Buffer number, or 0 for current buffer.
+                     When omitted, disable diagnostics in all buffers.
+      • {namespace}  (integer|nil) Only disable diagnostics for the given
                      namespace.
 
 enable({bufnr}, {namespace})                         *vim.diagnostic.enable()*
     Enable diagnostics in the given buffer.
 
     Parameters: ~
-      • {bufnr}      (number|nil) Buffer number, or 0 for current buffer. When
-                     omitted, enable diagnostics in all buffers.
-      • {namespace}  (number|nil) Only enable diagnostics for the given
+      • {bufnr}      (integer|nil) Buffer number, or 0 for current buffer.
+                     When omitted, enable diagnostics in all buffers.
+      • {namespace}  (integer|nil) Only enable diagnostics for the given
                      namespace.
 
 fromqflist({list})                               *vim.diagnostic.fromqflist()*
     Convert a list of quickfix items to a list of diagnostics.
 
     Parameters: ~
-      • {list}  (table) A list of quickfix items from |getqflist()| or
+      • {list}  table[] List of quickfix items from |getqflist()| or
                 |getloclist()|.
 
     Return: ~
@@ -457,9 +481,12 @@ fromqflist({list})                               *vim.diagnostic.fromqflist()*
 get({bufnr}, {opts})                                    *vim.diagnostic.get()*
     Get current diagnostics.
 
+    Modifying diagnostics in the returned table has no effect. To set
+    diagnostics in a buffer, use |vim.diagnostic.set()|.
+
     Parameters: ~
-      • {bufnr}  (number|nil) Buffer number to get diagnostics from. Use 0 for
-                 current buffer or nil for all buffers.
+      • {bufnr}  (integer|nil) Buffer number to get diagnostics from. Use 0
+                 for current buffer or nil for all buffers.
       • {opts}   (table|nil) A table with the following keys:
                  • namespace: (number) Limit diagnostics to the given
                    namespace.
@@ -467,13 +494,13 @@ get({bufnr}, {opts})                                    *vim.diagnostic.get()*
                  • severity: See |diagnostic-severity|.
 
     Return: ~
-        Diagnostic [] table A list of diagnostic items |diagnostic-structure|.
+        Diagnostic [] table A list of diagnostic items |diagnostic-structure|. Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are guaranteed to be present.
 
 get_namespace({namespace})                    *vim.diagnostic.get_namespace()*
     Get namespace metadata.
 
     Parameters: ~
-      • {namespace}  (number) Diagnostic namespace
+      • {namespace}  (integer) Diagnostic namespace
 
     Return: ~
         (table) Namespace metadata
@@ -560,17 +587,17 @@ hide({namespace}, {bufnr})                             *vim.diagnostic.hide()*
     |vim.diagnostic.disable()|.
 
     Parameters: ~
-      • {namespace}  (number|nil) Diagnostic namespace. When omitted, hide diagnostics from all
+      • {namespace}  (integer|nil) Diagnostic namespace. When omitted, hide diagnostics from all
                      namespaces.
-      • {bufnr}      (number|nil) Buffer number, or 0 for current buffer. When
-                     omitted, hide diagnostics in all buffers.
+      • {bufnr}      (integer|nil) Buffer number, or 0 for current buffer.
+                     When omitted, hide diagnostics in all buffers.
 
 is_disabled({bufnr}, {namespace})               *vim.diagnostic.is_disabled()*
     Check whether diagnostics are disabled in a given buffer.
 
     Parameters: ~
-      • {bufnr}      (number|nil) Buffer number, or 0 for current buffer.
-      • {namespace}  (number|nil) Diagnostic namespace. When omitted, checks if all diagnostics are
+      • {bufnr}      (integer|nil) Buffer number, or 0 for current buffer.
+      • {namespace}  (integer|nil) Diagnostic namespace. When omitted, checks if all diagnostics are
                      disabled in {bufnr}. Otherwise, only checks if
                      diagnostics from {namespace} are disabled.
 
@@ -582,16 +609,14 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
     Parse a diagnostic from a string.
 
     For example, consider a line of output from a linter: >
-
-     WARNING filename:27:3: Variable 'foo' does not exist
+        WARNING filename:27:3: Variable 'foo' does not exist
 <
 
     This can be parsed into a diagnostic |diagnostic-structure| with: >lua
-
-       local s = "WARNING filename:27:3: Variable 'foo' does not exist"
-       local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
-       local groups = { "severity", "lnum", "col", "message" }
-       vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
+        local s = "WARNING filename:27:3: Variable 'foo' does not exist"
+        local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
+        local groups = { "severity", "lnum", "col", "message" }
+        vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
 <
 
     Parameters: ~
@@ -663,7 +688,7 @@ open_float({opts}, {...})                        *vim.diagnostic.open_float()*
                   from |vim.diagnostic.config()|.
 
     Return: ~
-        number|nil, number|nil: ({float_bufnr}, {win_id})
+        integer|nil, integer|nil: ({float_bufnr}, {win_id})
 
 reset({namespace}, {bufnr})                           *vim.diagnostic.reset()*
     Remove all diagnostics from the given namespace.
@@ -674,17 +699,17 @@ reset({namespace}, {bufnr})                           *vim.diagnostic.reset()*
     re-displayed, use |vim.diagnostic.hide()|.
 
     Parameters: ~
-      • {namespace}  (number|nil) Diagnostic namespace. When omitted, remove diagnostics from all
+      • {namespace}  (integer|nil) Diagnostic namespace. When omitted, remove diagnostics from all
                      namespaces.
-      • {bufnr}      (number|nil) Remove diagnostics for the given buffer.
+      • {bufnr}      (integer|nil) Remove diagnostics for the given buffer.
                      When omitted, diagnostics are removed for all buffers.
 
 set({namespace}, {bufnr}, {diagnostics}, {opts})        *vim.diagnostic.set()*
     Set diagnostics for the given namespace and buffer.
 
     Parameters: ~
-      • {namespace}    (number) The diagnostic namespace
-      • {bufnr}        (number) Buffer number
+      • {namespace}    (integer) The diagnostic namespace
+      • {bufnr}        (integer) Buffer number
       • {diagnostics}  (table) A list of diagnostic items
                        |diagnostic-structure|
       • {opts}         (table|nil) Display options to pass to
@@ -723,9 +748,9 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
     Display diagnostics for the given namespace and buffer.
 
     Parameters: ~
-      • {namespace}    (number|nil) Diagnostic namespace. When omitted, show diagnostics from all
+      • {namespace}    (integer|nil) Diagnostic namespace. When omitted, show diagnostics from all
                        namespaces.
-      • {bufnr}        (number|nil) Buffer number, or 0 for current buffer.
+      • {bufnr}        (integer|nil) Buffer number, or 0 for current buffer.
                        When omitted, show diagnostics in all buffers.
       • {diagnostics}  (table|nil) The diagnostics to display. When omitted,
                        use the saved diagnostics for the given namespace and