From 26765e8461c1ba1e9a351632212cf89900221781 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 8 Apr 2024 00:41:41 +0200 Subject: feat(diagnostic): is_enabled, enable(…, enable:boolean) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: `vim.diagnostic.is_disabled` and `vim.diagnostic.disable` are unnecessary and inconsistent with the "toggle" pattern (established starting with `vim.lsp.inlay_hint`, see https://github.com/neovim/neovim/pull/25512#pullrequestreview-1676750276 As a reminder, the rationale is: - we always need `enable()` - we always end up needing `is_enabled()` - "toggle" can be achieved via `enable(not is_enabled())` - therefore, - `toggle()` and `disable()` are redundant - `is_disabled()` is a needless inconsistency Solution: - Introduce `vim.diagnostic.is_enabled`, and `vim.diagnostic.enable(…, enable:boolean)` - Note: Future improvement would be to add an `enable()` overload `enable(enable:boolean, opts: table)`. - Deprecate `vim.diagnostic.is_disabled`, `vim.diagnostic.disable` --- runtime/doc/deprecated.txt | 5 ++++- runtime/doc/develop.txt | 5 ++++- runtime/doc/diagnostic.txt | 38 ++++++++++++++++++-------------------- runtime/doc/news-0.9.txt | 2 +- runtime/doc/news.txt | 8 ++++++++ 5 files changed, 35 insertions(+), 23 deletions(-) (limited to 'runtime/doc') diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 5ac4ad4ce2..1b57f34896 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -80,12 +80,15 @@ HIGHLIGHTS - *hl-VertSplit* Use |hl-WinSeparator| instead. LSP DIAGNOSTICS +- *vim.diagnostic.disable()* Use |vim.diagnostic.enable()| +- *vim.diagnostic.is_disabled()* Use |vim.diagnostic.is_enabled()| + For each of the functions below, use the corresponding function in |vim.diagnostic| instead (unless otherwise noted). For example, use |vim.diagnostic.get()| instead of |vim.lsp.diagnostic.get()|. - *vim.lsp.diagnostic.clear()* Use |vim.diagnostic.hide()| instead. -- *vim.lsp.diagnostic.disable()* +- *vim.lsp.diagnostic.disable()* Use |vim.diagnostic.enable()| instead. - *vim.lsp.diagnostic.display()* Use |vim.diagnostic.show()| instead. - *vim.lsp.diagnostic.enable()* - *vim.lsp.diagnostic.get()* diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 767f46ad1e..a7373c84b3 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -383,9 +383,12 @@ Use existing common {verb} names (actions) if possible: - try_{verb}: Best-effort operation, failure returns null or error obj Do NOT use these deprecated verbs: + - disable: Prefer `enable(enable: boolean)`. + - is_disabled: Prefer `is_enabled()`. - list: Redundant with "get" - - show: Redundant with "print", "echo" - notify: Redundant with "print", "echo" + - show: Redundant with "print", "echo" + - toggle: Prefer `enable(not is_enabled())`. Use consistent names for {noun} (nouns) in API functions: buffer is called "buf" everywhere, not "buffer" in some places and "buf" in others. diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index a9172119d0..1f3f1c80fe 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -616,23 +616,19 @@ count({bufnr}, {opts}) *vim.diagnostic.count()* (`table`) Table with actually present severity values as keys (see |diagnostic-severity|) and integer counts as values. -disable({bufnr}, {namespace}) *vim.diagnostic.disable()* - Disable diagnostics in the given buffer. +enable({bufnr}, {namespace}, {enable}) *vim.diagnostic.enable()* + Enables or disables diagnostics. - Parameters: ~ - • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When - omitted, disable diagnostics in all buffers. - • {namespace} (`integer?`) Only disable diagnostics for the given - namespace. - -enable({bufnr}, {namespace}) *vim.diagnostic.enable()* - Enable diagnostics in the given buffer. + To "toggle", pass the inverse of `is_enabled()`: >lua + vim.diagnostic.enable(0, not vim.diagnostic.is_enabled()) +< Parameters: ~ - • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When - omitted, enable diagnostics in all buffers. - • {namespace} (`integer?`) Only enable diagnostics for the given - namespace. + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer, or + `nil` for all buffers. + • {namespace} (`integer?`) Only for the given namespace, or `nil` for + all. + • {enable} (`boolean?`) true/nil to enable, false to disable fromqflist({list}) *vim.diagnostic.fromqflist()* Convert a list of quickfix items to a list of diagnostics. @@ -733,7 +729,7 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* diagnostics, use |vim.diagnostic.reset()|. To hide diagnostics and prevent them from re-displaying, use - |vim.diagnostic.disable()|. + |vim.diagnostic.enable()|. Parameters: ~ • {namespace} (`integer?`) Diagnostic namespace. When omitted, hide @@ -741,14 +737,16 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* • {bufnr} (`integer?`) 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. +is_enabled({bufnr}, {namespace}) *vim.diagnostic.is_enabled()* + Check whether diagnostics are enabled. + + Note: ~ + • This API is pre-release (unstable). Parameters: ~ • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. - • {namespace} (`integer?`) Diagnostic namespace. When omitted, checks - if all diagnostics are disabled in {bufnr}. Otherwise, - only checks if diagnostics from {namespace} are disabled. + • {namespace} (`integer?`) Diagnostic namespace, or `nil` for all + diagnostics in {bufnr}. Return: ~ (`boolean`) diff --git a/runtime/doc/news-0.9.txt b/runtime/doc/news-0.9.txt index 789bc9e0bc..f1f3ac6954 100644 --- a/runtime/doc/news-0.9.txt +++ b/runtime/doc/news-0.9.txt @@ -162,7 +162,7 @@ The following new APIs or features were added. • |vim.diagnostic| now supports LSP DiagnosticsTag. See: https://microsoft.github.io/language-server-protocol/specification/#diagnosticTag -• |vim.diagnostic.is_disabled()| checks if diagnostics are disabled in a given +• vim.diagnostic.is_disabled() checks if diagnostics are disabled in a given buffer or namespace. • Treesitter captures can now be transformed by directives. This will allow diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index ae5f808a9c..8609d84506 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -328,6 +328,8 @@ The following new APIs and features were added. |vim.diagnostic.get()| when only the number of diagnostics is needed, but not the diagnostics themselves. +• Introduced |vim.diagnostic.is_enabled()| + • |vim.deepcopy()| has a `noref` argument to avoid hashing table values. • Terminal buffers emit a |TermRequest| autocommand event when the child @@ -419,6 +421,8 @@ The following changes to existing APIs or features add new behavior. • |vim.diagnostic.get()| and |vim.diagnostic.count()| accept multiple namespaces rather than just a single namespace. +• |vim.diagnostic.enable()| accepts an `enabled` boolean parameter. + • Extmarks now fully support multi-line ranges, and a single extmark can be used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()| API function already allowed you to define such ranges, but highlight regions @@ -520,6 +524,10 @@ release. - |nvim_win_get_option()| Use |nvim_get_option_value()| instead. - |nvim_win_set_option()| Use |nvim_set_option_value()| instead. +• vim.diagnostic functions: + - |vim.diagnostic.disable()| + - |vim.diagnostic.is_disabled()| + • vim.lsp functions: - |vim.lsp.util.get_progress_messages()| Use |vim.lsp.status()| instead. - |vim.lsp.get_active_clients()| Use |vim.lsp.get_clients()| instead. -- cgit From 5ed9916a28b9a09d2e5629f3e4e5b0e81403ded7 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 15 Apr 2024 18:35:59 +0200 Subject: feat(diagnostic): enable(…, opts) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: vim.diagnostic.enable() does not match the signature of vim.lsp.inlay_hint.enable() Solution: - Change the signature so that the first 2 args are (bufnr, enable). - Introduce a 3rd `opts` arg. - Currently it only supports `opts.ns_id`. --- runtime/doc/develop.txt | 2 ++ runtime/doc/diagnostic.txt | 20 ++++++++++++++------ runtime/doc/news.txt | 3 ++- 3 files changed, 18 insertions(+), 7 deletions(-) (limited to 'runtime/doc') diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index a7373c84b3..6c27e4775f 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -372,11 +372,13 @@ Use existing common {verb} names (actions) if possible: - create: Creates a new (non-trivial) thing (TODO: rename to "def"?) - del: Deletes a thing (or group of things) - detach: Dispose attached listener (TODO: rename to "un"?) + - enable: Enables/disables functionality. - eval: Evaluates an expression - exec: Executes code - fmt: Formats - get: Gets things (often by a query) - inspect: Presents a high-level, often interactive, view + - is_enabled: Checks if functionality is enabled. - open: Opens something (a buffer, window, …) - parse: Parses something into a structured form - set: Sets a thing (or group of things) diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 1f3f1c80fe..1826cc4c08 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -367,6 +367,13 @@ Lua module: vim.diagnostic *diagnostic-api* • {user_data}? (`any`) arbitrary data plugins can add • {namespace}? (`integer`) +*vim.diagnostic.Filter* + Extends: |vim.diagnostic.Opts| + + + Fields: ~ + • {ns_id}? (`integer`) Namespace + *vim.diagnostic.GetOpts* A table with the following keys: @@ -616,7 +623,7 @@ count({bufnr}, {opts}) *vim.diagnostic.count()* (`table`) Table with actually present severity values as keys (see |diagnostic-severity|) and integer counts as values. -enable({bufnr}, {namespace}, {enable}) *vim.diagnostic.enable()* +enable({bufnr}, {enable}, {opts}) *vim.diagnostic.enable()* Enables or disables diagnostics. To "toggle", pass the inverse of `is_enabled()`: >lua @@ -624,11 +631,12 @@ enable({bufnr}, {namespace}, {enable}) *vim.diagnostic.enable()* < Parameters: ~ - • {bufnr} (`integer?`) Buffer number, or 0 for current buffer, or - `nil` for all buffers. - • {namespace} (`integer?`) Only for the given namespace, or `nil` for - all. - • {enable} (`boolean?`) true/nil to enable, false to disable + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer, or + `nil` for all buffers. + • {enable} (`boolean?`) true/nil to enable, false to disable + • {opts} (`vim.diagnostic.Filter?`) Filter by these opts, or `nil` + for all. Only `ns_id` is supported, currently. See + |vim.diagnostic.Filter|. fromqflist({list}) *vim.diagnostic.fromqflist()* Convert a list of quickfix items to a list of diagnostics. diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 8609d84506..d320db4e51 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -421,7 +421,8 @@ The following changes to existing APIs or features add new behavior. • |vim.diagnostic.get()| and |vim.diagnostic.count()| accept multiple namespaces rather than just a single namespace. -• |vim.diagnostic.enable()| accepts an `enabled` boolean parameter. +• |vim.diagnostic.enable()| gained new parameters, and the old signature is + deprecated. • Extmarks now fully support multi-line ranges, and a single extmark can be used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()| -- cgit