diff options
Diffstat (limited to 'runtime/doc/develop.txt')
| -rw-r--r-- | runtime/doc/develop.txt | 21 |
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* |