From 95cbedaa1798a7c1489b68dd60380a41443ed34b Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 18 Jan 2024 00:14:48 -0800 Subject: [PATCH] docs: various #25289 Co-authored-by: Jongwook Choi Co-authored-by: Oliver Marriott Co-authored-by: Benoit de Chezelles Co-authored-by: Jongwook Choi --- CONTRIBUTING.md | 12 +++++++----- cmake.deps/CMakeLists.txt | 1 + runtime/doc/autocmd.txt | 5 ++--- runtime/doc/lsp.txt | 30 ++++++++++++++++------------- runtime/doc/motion.txt | 2 +- runtime/doc/recover.txt | 8 ++++---- runtime/lua/vim/lsp.lua | 17 ++++++++-------- runtime/lua/vim/lsp/inlay_hint.lua | 8 +++++++- src/nvim/README.md | 6 ++++++ src/nvim/tui/tui.c | 6 ++++++ test/functional/lua/watch_spec.lua | 5 ++++- test/functional/plugin/lsp_spec.lua | 5 ++++- 12 files changed, 67 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fe735cad2..ef83c22155 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -149,8 +149,10 @@ View the [Clang report] to see potential bugs found by the Clang ### Coverity -[Coverity](https://scan.coverity.com/projects/neovim-neovim) runs against the -master build. To view the defects, just request access; you will be approved. +Coverity runs against the master build. To view the defects you must +[request access](https://scan.coverity.com/projects/neovim-neovim) (Coverity +does not have a "public" view), then you will be approved as soon as +a maintainer sees the email. - Use this format for commit messages (where `{id}` is the CID (Coverity ID); ([example](https://github.com/neovim/neovim/pull/804))): @@ -283,7 +285,7 @@ If you need to modify or debug the documentation flow, these are the main files: ### Lua docstrings Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return -types, etc. See [:help dev-doc-lua][dev-doc-lua]. +types, etc. See [:help dev-lua-doc][dev-lua-doc]. - The template for function documentation is: ```lua @@ -331,8 +333,8 @@ as context, use the `-W` argument as well. [complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow [conventional_commits]: https://www.conventionalcommits.org [dev-doc-guide]: https://neovim.io/doc/user/develop.html#dev-doc -[dev-doc-lua]: https://neovim.io/doc/user/develop.html#dev-lua-doc -[LuaLS]: https://github.com/LuaLS/lua-language-server/wiki/Annotations +[dev-lua-doc]: https://neovim.io/doc/user/develop.html#dev-lua-doc +[LuaLS]: https://luals.github.io/wiki/annotations/ [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html [gh]: https://cli.github.com/ [git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git diff --git a/cmake.deps/CMakeLists.txt b/cmake.deps/CMakeLists.txt index 90b752d250..afc4da8def 100644 --- a/cmake.deps/CMakeLists.txt +++ b/cmake.deps/CMakeLists.txt @@ -37,6 +37,7 @@ option(USE_BUNDLED "Use bundled dependencies." ON) option(USE_BUNDLED_LIBUV "Use the bundled libuv." ${USE_BUNDLED}) option(USE_BUNDLED_LIBVTERM "Use the bundled libvterm." ${USE_BUNDLED}) option(USE_BUNDLED_LPEG "Use the bundled lpeg." ${USE_BUNDLED}) +# PUC Lua is only used for tests, unless explicitly requested. option(USE_BUNDLED_LUA "Use the bundled version of lua." OFF) option(USE_BUNDLED_LUAJIT "Use the bundled version of luajit." ${USE_BUNDLED}) option(USE_BUNDLED_LUV "Use the bundled version of luv." ${USE_BUNDLED}) diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index ce3af01073..e43574fe86 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -784,9 +784,6 @@ OptionSet After setting an option (except during are not global-local it is the old local value. - OptionSet is not triggered on startup and for - the 'key' option for obvious reasons. - Usage example: Check for the existence of the directory in the 'backupdir' and 'undodir' options, create the directory if it doesn't @@ -800,6 +797,8 @@ OptionSet After setting an option (except during Non-recursive: |:set| in the autocommand does not trigger OptionSet again. + Not triggered on startup. + *QuickFixCmdPre* QuickFixCmdPre Before a quickfix command is run (|:make|, |:lmake|, |:grep|, |:lgrep|, |:grepadd|, diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index e3fc616df4..ad1b838578 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -911,9 +911,8 @@ start({config}, {opts}) *vim.lsp.start()* • `name` arbitrary name for the LSP client. Should be unique per language server. - • `cmd` command (in list form) used to start the language server. Must be - absolute, or found on `$PATH`. Shell constructs like `~` are not - expanded. + • `cmd` command string[] or function, described at + |vim.lsp.start_client()|. • `root_dir` path to the project root. By default this is used to decide if an existing client should be re-used. The example above uses |vim.fs.find()| and |vim.fs.dirname()| to detect the root by traversing @@ -953,15 +952,16 @@ start_client({config}) *vim.lsp.start_client()* Parameters: ~ • {config} (`lsp.ClientConfig`) Configuration for the server: - • cmd: (string[]|fun(dispatchers: table):table) command a - list of strings treated like |jobstart()|. The command - must launch the language server process. `cmd` can also be - a function that creates an RPC client. The function - receives a dispatchers table and must return a table with - the functions `request`, `notify`, `is_closing` and - `terminate` See |vim.lsp.rpc.request()| and - |vim.lsp.rpc.notify()| For TCP there is a built-in rpc - client factory: |vim.lsp.rpc.connect()| + • cmd: (string[]|fun(dispatchers: table):table) command + string[] that launches the language server (treated as in + |jobstart()|, must be absolute or on `$PATH`, shell + constructs like "~" are not expanded), or function that + creates an RPC client. Function receives a `dispatchers` + table and returns a table with member functions `request`, + `notify`, `is_closing` and `terminate`. See + |vim.lsp.rpc.request()|, |vim.lsp.rpc.notify()|. For TCP + there is a builtin RPC client factory: + |vim.lsp.rpc.connect()| • cmd_cwd: (string, default=|getcwd()|) Directory to launch the `cmd` process. Not related to `root_dir`. • cmd_env: (table) Environment flags to pass to the LSP on @@ -1479,7 +1479,11 @@ save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()* Lua module: vim.lsp.inlay_hint *lsp-inlay_hint* enable({bufnr}, {enable}) *vim.lsp.inlay_hint.enable()* - Enable/disable/toggle inlay hints for a buffer + Enables or disables inlay hints for a buffer. + + To "toggle", pass the inverse of `is_enabled()`: >lua + vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled()) +< Note: ~ This API is pre-release (unstable). diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index 03fe5c7b81..e80969c583 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -1048,7 +1048,7 @@ CTRL-I Go to [count] newer cursor position in jump list |tui-modifyOtherKeys| or |tui-csiu|, CTRL-I can be mapped separately from , on the condition that both keys are mapped, otherwise the mapping applies to - both. + both. Except in tmux: https://github.com/tmux/tmux/issues/2705 *:ju* *:jumps* :ju[mps] Print the jump list (not a motion command). diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt index e6b5b06744..4312716b22 100644 --- a/runtime/doc/recover.txt +++ b/runtime/doc/recover.txt @@ -85,10 +85,10 @@ You can find this in the user manual, section |11.3|. *W325* The default |SwapExists| handler (|default-autocmds|) skips the |E325| prompt -(selects "(E)dit") if the swapfile owner process (1) is still running and (2) -was started by the current user. This presumes that you normally don't want -to be bothered with the |ATTENTION| message just because you happen to edit -the same file from multiple Nvim instances. In the worst case (a system +(and automatically chooses "(E)dit") if the swapfile owner process is still +running and owned by the current user. This presumes that you normally don't +want to be bothered with the |ATTENTION| message just because you happen to +edit the same file from multiple Nvim instances. In the worst case (a system crash) there will be more than one swapfile for the file; use |:recover| to inspect all of its swapfiles. diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index a02a93d559..f3448209ba 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -488,8 +488,7 @@ end --- See |vim.lsp.start_client()| for all available options. The most important are: --- --- - `name` arbitrary name for the LSP client. Should be unique per language server. ---- - `cmd` command (in list form) used to start the language server. Must be absolute, or found on ---- `$PATH`. Shell constructs like `~` are not expanded. +--- - `cmd` command string[] or function, described at |vim.lsp.start_client()|. --- - `root_dir` path to the project root. By default this is used to decide if an existing client --- should be re-used. The example above uses |vim.fs.find()| and |vim.fs.dirname()| to detect the --- root by traversing the file system upwards starting from the current directory until either @@ -666,13 +665,13 @@ end --- Field `cmd` in {config} is required. --- ---@param config (lsp.ClientConfig) Configuration for the server: ---- - cmd: (string[]|fun(dispatchers: table):table) command a list of ---- strings treated like |jobstart()|. The command must launch the language server ---- process. `cmd` can also be a function that creates an RPC client. ---- The function receives a dispatchers table and must return a table with the ---- functions `request`, `notify`, `is_closing` and `terminate` ---- See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()| ---- For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()| +--- - cmd: (string[]|fun(dispatchers: table):table) command string[] that launches the language +--- server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like +--- "~" are not expanded), or function that creates an RPC client. Function receives +--- a `dispatchers` table and returns a table with member functions `request`, `notify`, +--- `is_closing` and `terminate`. +--- See |vim.lsp.rpc.request()|, |vim.lsp.rpc.notify()|. +--- For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()| --- --- - cmd_cwd: (string, default=|getcwd()|) Directory to launch --- the `cmd` process. Not related to `root_dir`. diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua index ce1680549e..4816b873ba 100644 --- a/runtime/lua/vim/lsp/inlay_hint.lua +++ b/runtime/lua/vim/lsp/inlay_hint.lua @@ -368,7 +368,13 @@ function M.is_enabled(bufnr) return bufstates[bufnr] and bufstates[bufnr].enabled or false end ---- Enable/disable/toggle inlay hints for a buffer +--- Enables or disables inlay hints for a buffer. +--- +--- To "toggle", pass the inverse of `is_enabled()`: +--- +--- ```lua +--- vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled()) +--- ``` --- --- @param bufnr (integer|nil) Buffer handle, or 0 or nil for current --- @param enable (boolean|nil) true/nil to enable, false to disable diff --git a/src/nvim/README.md b/src/nvim/README.md index b264c918b6..9ef39cc90f 100644 --- a/src/nvim/README.md +++ b/src/nvim/README.md @@ -255,6 +255,12 @@ region is repainted internally. To also highlight excess internal redraws, use - http://bazaar.launchpad.net/~libvterm/libvterm/trunk/view/head:/doc/seqs.txt - http://invisible-island.net/xterm/ctlseqs/ctlseqs.html +Data structures +--------------- + +Buffer text is stored as a tree of line segments, defined in [memline.c](https://github.com/neovim/neovim/blob/v0.9.5/src/nvim/memline.c#L8-L35). +The central idea is found in [ml_find_line](https://github.com/neovim/neovim/blob/v0.9.5/src/nvim/memline.c#L2800). + Nvim lifecycle -------------- diff --git a/src/nvim/tui/tui.c b/src/nvim/tui/tui.c index 9cd0c64bfe..6b8b73a2a0 100644 --- a/src/nvim/tui/tui.c +++ b/src/nvim/tui/tui.c @@ -1312,6 +1312,9 @@ void tui_default_colors_set(TUIData *tui, Integer rgb_fg, Integer rgb_bg, Intege invalidate(tui, 0, tui->grid.height, 0, tui->grid.width); } +/// Flushes TUI grid state to a buffer (which is later flushed to the TTY by `flush_buf`). +/// +/// @see flush_buf void tui_flush(TUIData *tui) { UGrid *grid = &tui->grid; @@ -2327,6 +2330,9 @@ static size_t flush_buf_end(TUIData *tui, char *buf, size_t len) return offset; } +/// Flushes the rendered buffer to the TTY. +/// +/// @see tui_flush static void flush_buf(TUIData *tui) { uv_write_t req; diff --git a/test/functional/lua/watch_spec.lua b/test/functional/lua/watch_spec.lua index 106d40fe0e..044d707499 100644 --- a/test/functional/lua/watch_spec.lua +++ b/test/functional/lua/watch_spec.lua @@ -99,7 +99,10 @@ describe('vim._watch', function() describe('poll', function() it('detects file changes', function() - skip(is_os('bsd'), 'bsd only reports rename on folders if file inside change') + skip( + is_os('bsd'), + 'kqueue only reports events on watched folder itself, not contained files #26110' + ) local root_dir = vim.uv.fs_mkdtemp(vim.fs.dirname(helpers.tmpname()) .. '/nvim_XXXXXXXXXX') local result = exec_lua( diff --git a/test/functional/plugin/lsp_spec.lua b/test/functional/plugin/lsp_spec.lua index 252931eccb..b602143443 100644 --- a/test/functional/plugin/lsp_spec.lua +++ b/test/functional/plugin/lsp_spec.lua @@ -4261,7 +4261,10 @@ describe('LSP', function() describe('vim.lsp._watchfiles', function() it('sends notifications when files change', function() - skip(is_os('bsd'), 'bsd only reports rename on folders if file inside change') + skip( + is_os('bsd'), + 'kqueue only reports events on watched folder itself, not contained files #26110' + ) local root_dir = tmpname() os.remove(root_dir) mkdir(root_dir)