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

1 files changed, 18 insertions, 3 deletions

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index a61c569a67..d3170f114f 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -300,7 +300,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
     --- @returns false if client should cancel the paste.
 
 
-LUA STDLIB DESIGN GUIDELINES                            *dev-lua*
+STDLIB DESIGN GUIDELINES                                             *dev-lua*
 
 See also |dev-naming|.
 
@@ -337,7 +337,7 @@ preference):
     way. Advantage is that propagation happens for free and it's harder to
     accidentally swallow errors. (E.g. using
     `uv_handle/pipe:write()` without checking return values is common.)
-4. `on_error` parameter
+4. `on_error` callback
   - For async and "visitors" traversing a graph, where many errors may be
     collected while work continues.
 5. `vim.notify` (sometimes with optional `opts.silent` (async, visitors ^))
@@ -376,6 +376,10 @@ Where possible, these patterns apply to _both_ Lua and the API:
   - See |vim.lsp.inlay_hint.enable()| and |vim.lsp.inlay_hint.is_enabled()|
     for a reference implementation of these "best practices".
   - NOTE: open questions: https://github.com/neovim/neovim/issues/28603
+- Transformation functions should also have a filter functionality when
+  appropriate. That is, when the function returns a nil value it "filters" its
+  input, otherwise the transformed value is used.
+  - Example: |vim.diagnostic.config.format()|
 
 API DESIGN GUIDELINES                                   *dev-api*
 
@@ -434,7 +438,9 @@ Use existing common {verb} names (actions) if possible:
     - eval:         Evaluates an expression
     - exec:         Executes code, may return a result
     - fmt:          Formats
-    - get:          Gets things (often by a query)
+    - get:          Gets things. Two variants (overloads):
+                    1. `get<T>(id: int): T` returns one item.
+                    2. `get<T>(filter: dict): T[]` returns a list.
     - inspect:      Presents a high-level, often interactive, view
     - is_enabled:   Checks if functionality is enabled.
     - open:         Opens something (a buffer, window, …)
@@ -506,6 +512,15 @@ be a parameter (typically manifest as mutually-exclusive buf/win/… flags like
 - Example: `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
   and uses the "del" {verb}.
 
+                                                        *dev-namespace-name*
+Use namespace names like `nvim.foo.bar`: >
+    vim.api.nvim_create_namespace('nvim.lsp.codelens')
+<
+
+                                                        *dev-augroup-name*
+Use autocommand group names like `nvim.foo.bar`: >
+    vim.api.nvim_create_augroup('nvim.treesitter.dev')
+<
 
 INTERFACE PATTERNS                                      *dev-api-patterns*