diff options
| -rw-r--r-- | CONTRIBUTING.md | 8 | ||||
| -rw-r--r-- | runtime/doc/deprecated.txt | 1 | ||||
| -rw-r--r-- | runtime/doc/develop.txt | 40 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 22 | ||||
| -rw-r--r-- | src/nvim/main.c | 2 | ||||
| -rw-r--r-- | test/functional/api/server_notifications_spec.lua | 5 |
7 files changed, 51 insertions, 31 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27fd2b97bb..24b8cf60ed 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,10 +28,10 @@ Reporting problems Developer guidelines -------------------- -- Nvim contributors should read `:help dev`. -- External UI developers should read `:help dev-ui`. -- API client developers should read `:help dev-api-client`. -- Nvim developers are _strongly encouraged_ to install `ninja` for faster builds. +- Read `:help dev` if you are working on Nvim core. +- Read `:help dev-ui` if you are developing a UI. +- Read `:help dev-api-client` if you are developing an API client. +- Install `ninja` for faster builds of Nvim. ``` sudo apt-get install ninja-build make distclean diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 861aed4884..36e6cc89e6 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -14,7 +14,6 @@ updated. API ~ *nvim_buf_clear_highlight()* Use |nvim_buf_clear_namespace()| instead. -*nvim_buf_set_virtual_text()* Use |nvim_buf_set_extmark()| instead. *nvim_command_output()* Use |nvim_exec()| instead. *nvim_execute_lua()* Use |nvim_exec_lua()| instead. diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 4776aaab64..401ad0e536 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -127,14 +127,20 @@ Sometimes a GUI or other application may want to force a provider to DOCUMENTATION *dev-doc* -- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to document - differences from Vim; no other distinction is necessary. -- If a Vim feature is removed, delete its help section and move its tag to - |vim_diff.txt|. -- Move deprecated features to |deprecated.txt|. +- "Just say it". Avoid mushy, colloquial phrasing in all documentation + (docstrings, user manual, website materials, newsletters, …). Don't mince + words. Personality and flavor, used sparingly, are welcome--but in general, + optimize for the reader's time and energy: be "precise yet concise". + - Prefer the active voice: "Foo does X", not "X is done by Foo". +- Vim differences: + - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog + differences from Vim; no other distinction is necessary. + - If a Vim feature is removed, delete its help section and move its tag to + |vim_diff.txt|. +- Mention deprecated features in |deprecated.txt| and delete their old doc. - Use consistent language. - - "terminal" in a help tag always means "the embedded terminal emulator", not - "the user host terminal". + - "terminal" in a help tag always means "the embedded terminal emulator", + not "the user host terminal". - Use "tui-" to prefix help tags related to the host terminal, and "TUI" in prose if possible. - Docstrings: do not start parameter descriptions with "The" or "A" unless it @@ -222,13 +228,13 @@ LUA *dev-lua* - Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or pseudo-OOP designs. Plugin authors just want functions to call, they don't - want to learn a big, fancy inheritance hierarchy. So we should avoid complex - objects: tables are usually better. + want to learn a big, fancy inheritance hierarchy. Thus avoid specialized + objects; tables or values are usually better. API *dev-api* -Use this template to name new API functions: +Use this template to name new RPC |API| functions: nvim_{thing}_{action}_{arbitrary-qualifiers} If the function acts on an object then {thing} is the name of that object @@ -358,9 +364,17 @@ External UIs are expected to implement these common features: NAMING *dev-naming* -Naming is very important. Consistent naming in the API and UI helps users -discover and intuitively understand related "families" of things. It reduces -cognitive burden. +Naming is important. Consistent naming in the API and UI helps both users and +developers discover and intuitively understand related concepts ("families"), +and reduces cognitive burden. Discoverability encourages code re-use and +likewise avoids redundant, overlapping mechanisms, which reduces code +surface-area, and thereby minimizes bugs... + +Naming conventions ~ + +Use the "on_" prefix to name event handlers and also the interface for +"registering" such handlers (on_key). The dual nature is acceptable to avoid +a confused collection of naming conventions for these related concepts. vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 5e52a5bcf7..16d2fcd424 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -572,11 +572,11 @@ If you want to exclude visual selections from highlighting on yank, use vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* Highlights the yanked text. The fields of the optional dict {opts} control the highlight: - - {higroup} highlight group for yanked region (default `"IncSearch"`) + - {higroup} highlight group for yanked region (default |hl-IncSearch|) - {timeout} time in ms before highlight is cleared (default `150`) - {on_macro} highlight when executing macro (default `false`) - {on_visual} highlight when yanking visual selection (default `true`) - - {event} event structure (default `vim.v.event`) + - {event} event structure (default |v:event|) vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclusive}) *vim.highlight.range()* diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 27c4b82aca..5bf9bc5a47 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -6,16 +6,16 @@ Differences between Nvim and Vim *vim-differences* -Nvim differs from Vim in many ways, although editor and VimL features are -mostly identical. This document is a complete and centralized reference of -the differences. +Nvim differs from Vim in many ways, although editor and Vimscript (not +Vim9script) features are mostly identical. This document is a complete and +centralized reference of the differences. Type |gO| to see the table of contents. ============================================================================== 1. Configuration *nvim-config* -- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for configuration. +- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for your |config|. - Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files. - Use `$XDG_DATA_HOME/nvim/shada/main.shada` instead of `.viminfo` for persistent session information. |shada| @@ -78,17 +78,19 @@ the differences. MAJOR COMPONENTS ~ API |API| -Lua scripting |lua| Job control |job-control| -Remote plugins |remote-plugin| +LSP framework |lsp| +Lua scripting |lua| +Parsing engine |treesitter| Providers Clipboard |provider-clipboard| Node.js plugins |provider-nodejs| Python plugins |provider-python| Ruby plugins |provider-ruby| +Remote plugins |remote-plugin| Shared data |shada| -Embedded terminal |terminal| -VimL parser |nvim_parse_expression()| +Terminal emulator |terminal| +Vimscript parser |nvim_parse_expression()| XDG base directories |xdg| USER EXPERIENCE ~ @@ -137,7 +139,7 @@ FEATURES ~ Command-line highlighting: The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted - using a built-in VimL expression parser. |expr-highlight| + using a built-in Vimscript expression parser. |expr-highlight| *E5408* *E5409* |input()|, |inputdialog()| support custom highlighting. |input()-highlight| *g:Nvim_color_cmdline* @@ -380,7 +382,7 @@ TUI: UI/Display: |Visual| selection highlights the character at cursor. |visual-use| -VimL (Vim script) compatibility: +Vimscript compatibility: `count` does not alias to |v:count| `errmsg` does not alias to |v:errmsg| `shell_error` does not alias to |v:shell_error| diff --git a/src/nvim/main.c b/src/nvim/main.c index 7d7eba2105..6738b93124 100644 --- a/src/nvim/main.c +++ b/src/nvim/main.c @@ -338,7 +338,7 @@ int main(int argc, char **argv) // prepare screen now, so external UIs can display messages starting = NO_BUFFERS; screenclear(); - TIME_MSG("initialized screen early for UI"); + TIME_MSG("init screen for UI"); } diff --git a/test/functional/api/server_notifications_spec.lua b/test/functional/api/server_notifications_spec.lua index 9ee2570798..047bbfeb21 100644 --- a/test/functional/api/server_notifications_spec.lua +++ b/test/functional/api/server_notifications_spec.lua @@ -5,6 +5,7 @@ local eq, clear, eval, command, nvim, next_msg = local meths = helpers.meths local exec_lua = helpers.exec_lua local retry = helpers.retry +local isCI = helpers.isCI describe('notify', function() local channel @@ -76,6 +77,10 @@ describe('notify', function() end) it('cancels stale events on channel close', function() + if isCI() then + pending('hangs on CI #14083 #15251') + return + end if helpers.pending_win32(pending) then return end local catchan = eval("jobstart(['cat'], {'rpc': v:true})") eq({id=catchan, stream='job', mode='rpc', client = {}}, exec_lua ([[ |