Merge #38370 from justinmk/doc2

.clangd

@@ -2,3 +2,5 @@ CompileFlags:
   CompilationDatabase: build/       # Search build/ directory for compile_commands.json
 Diagnostics:
   UnusedIncludes: None
+Documentation:
+  CommentFormat: Doxygen

Makefile

@@ -112,17 +112,18 @@ build/.ran-cmake: | deps
 	$(CMAKE) -B build -G $(CMAKE_GENERATOR) $(CMAKE_FLAGS) $(CMAKE_EXTRA_FLAGS) $(MAKEFILE_DIR)
 	$(TOUCH) $@
 
+ifneq ($(call filter-true,$(USE_BUNDLED)),)
+deps: ;
+else
 deps: | build/.ran-deps-cmake
-ifeq ($(call filter-true,$(USE_BUNDLED)),)
 	$(CMAKE) --build $(DEPS_BUILD_DIR)
-endif
 
-ifeq ($(call filter-true,$(USE_BUNDLED)),)
 $(DEPS_BUILD_DIR):
 	$(MKDIR) $@
 build/.ran-deps-cmake:: $(DEPS_BUILD_DIR)
 	$(CMAKE) -S $(MAKEFILE_DIR)/cmake.deps -B $(DEPS_BUILD_DIR) -G $(CMAKE_GENERATOR) $(DEPS_CMAKE_FLAGS)
 endif
+
 build/.ran-deps-cmake::
 	$(MKDIR) build
 	$(TOUCH) "$@"
@@ -136,6 +137,7 @@ else
 	@# Handle TEST_FILE=test_foo{,.res,.vim}.
 	$(SINGLE_MAKE) -C test/old/testdir NVIM_PRG=$(NVIM_PRG) SCRIPTS= $(MAKEOVERRIDES) $(patsubst %.vim,%,$(patsubst %.res,%,$(TEST_FILE)))
 endif
+
 # Build oldtest by specifying the relative .vim filename.
 .PHONY: phony_force
 test/old/testdir/%.vim: phony_force nvim

runtime/doc/lsp.txt

@@ -1157,7 +1157,13 @@ get_clients({filter})                                  *vim.lsp.get_clients()*
 get_configs({filter})                                  *vim.lsp.get_configs()*
     Get LSP configs.
 
-    Note: Will eagerly evaluate config files in `'runtimepath'` if necessary.
+    WARNING:
+    • May eagerly (prematurely!) evaluate config files in 'runtimepath'.
+    • Configs may be in a partial state if they have async properties such as
+      `on_dir()`.
+
+    Attributes: ~
+        Since: 0.12.0
 
     Parameters: ~
       • {filter}  (`table?`) Key-value pairs used to filter the returned

runtime/doc/lua-guide.txt

@@ -160,7 +160,6 @@ the cache manually first:
     package.loaded['myluamodule'] = nil
     require('myluamodule')    -- read and execute the module again from disk
 <
-------------------------------------------------------------------------------
 See also:
 • |lua-module-load|: how `require()` finds modules
 • |pcall()|
@@ -228,7 +227,6 @@ e.g., |autoload| functions have to be called with this syntax:
 >lua
     vim.fn['my#autoload#function']()
 <
-------------------------------------------------------------------------------
 See also:
 • |vimscript-functions|: descriptions of all Vimscript functions
 • |function-list|: Vimscript functions grouped by topic
@@ -287,7 +285,6 @@ To delete a variable, simply set it to `nil`:
 >lua
     vim.g.myvar = nil
 <
-------------------------------------------------------------------------------
 See also:
 • |lua-vim-variables|
 
@@ -384,7 +381,6 @@ window is used:
                                -- in current window only
     print(vim.wo[0].number)    --> true
 <
-------------------------------------------------------------------------------
 See also:
 • |lua-options|
 
@@ -473,7 +469,6 @@ A specific mapping can be removed with |vim.keymap.del()|:
     vim.keymap.del('n', '<Leader>ex1')
     vim.keymap.del({'n', 'c'}, '<Leader>ex2', {buffer = true})
 <
-------------------------------------------------------------------------------
 See also:
 • `vim.api.`|nvim_get_keymap()|:     return all global mapping
 • `vim.api.`|nvim_buf_get_keymap()|: return all mappings for buffer
@@ -646,7 +641,6 @@ the autocommands that are to be removed:
 Note: Autocommands in groups will only be removed if the `group` key is
 specified, even if another option matches it.
 
-------------------------------------------------------------------------------
 See also
 • |nvim_get_autocmds()|:  return all matching autocommands
 • |nvim_exec_autocmds()|: execute all matching autocommands

runtime/doc/lua.txt

@@ -1304,7 +1304,7 @@ vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
       • {backtrace}    (`boolean?`) Prints backtrace. Defaults to true.
 
     Return: ~
-        (`string?`) Deprecated message, or nil if no message was shown.
+        (`string?`) Deprecation message, or nil if no message was shown.
 
 vim.inspect()                                                  *vim.inspect()*
     Gets a human-readable representation of the given object.
@@ -5032,11 +5032,11 @@ vim.ui.open({path}, {opt})                                     *vim.ui.open()*
       • |vim.system()|
 
 vim.ui.progress_status()                            *vim.ui.progress_status()*
-    Gets the status of currently running progress messages, in a format
-    convenient for inclusion in 'statusline'.
+    Gets a status description summarizing currently running progress messages.
+    Convenient for inclusion in 'statusline'.
 
     Return: ~
-        (`string`) formatted text of progress status for statusline
+        (`string`) Progress status
 
 vim.ui.select({items}, {opts}, {on_choice})                  *vim.ui.select()*
     Prompts the user to pick from a list of items, allowing arbitrary

runtime/doc/news.txt

@@ -157,8 +157,6 @@ API
 • |vim.secure.read()| now returns `true` for trusted directories. Previously
   it would return `nil`, thus impossible to tell if the directory was actually
   trusted.
-• Added |vim.lsp.is_enabled()| to check if a given LSP config has been enabled
-  by |vim.lsp.enable()|.
 • |nvim_ui_send()| writes arbitrary data to a UI's stdout. Use this to write
   escape sequences to the terminal when Nvim is running in the |TUI|.
 • |nvim_echo()| can set the |ui-messages| kind with which to emit the message.
@@ -281,6 +279,7 @@ LSP
   non-applicable LSP clients.
 • |vim.lsp.is_enabled()| checks if a LSP config is enabled (without
   "resolving" it).
+• |vim.lsp.get_configs()| gets all LSP configs matching an optional filter.
 • Support for `workspace/diagnostic`: |vim.lsp.buf.workspace_diagnostics()|
   https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_dagnostics
 • Incremental selection is now supported via `textDocument/selectionRange`.
@@ -331,7 +330,6 @@ LSP
 • Support for `workspace/codeLens/refresh`:
   https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#codeLens_refresh
 • |gx| opens `textDocument/documentLink` items found at cursor.
-• |vim.lsp.get_configs()| can get all LSP configs matching certain conditions.
 
 LUA
 
@@ -466,8 +464,8 @@ UI
 • Cursor shape indicates when it is behind an unfocused floating window.
 • Improved LSP signature help rendering.
 • Multigrid UIs can call nvim_input_mouse with grid 0 to let Nvim decide the grid.
-• |vim.ui.progress_status()| returns a formatted string of currently
-running |progress-message|.
+• |vim.ui.progress_status()| returns a status description of currently running
+  |progress-message|s.
 
 VIMSCRIPT
 

runtime/doc/treesitter.txt

@@ -671,8 +671,9 @@ TSTree:root()                                                  *TSTree:root()*
 TREESITTER NODES                                    *treesitter-node* *TSNode*
 
 A "treesitter node" represents one specific element of the parsed contents of
-a buffer, which can be captured by a |Query| for, e.g., highlighting. It is a
-|userdata| reference to an object held by the treesitter library.
+a buffer, which can be captured by a |treesitter-query| for, e.g.,
+highlighting. It is a |userdata| reference to an object held by the treesitter
+library.
 
 An instance `TSNode` of a treesitter node supports the following methods.
 

runtime/doc/vimeval.txt

@@ -1436,7 +1436,7 @@ The sequence must be an even number of hex characters.  Example: >
 ------------------------------------------------------------------------------
 literal-string						*literal-string* *E115*
 
-'string'		string constant			*expr-'*
+`'string'`		string constant			*expr-'*
 
 Note that single quotes are used.
 

runtime/doc/vimfn.txt

@@ -10650,7 +10650,7 @@ string({expr})                                                        *string()*
 		parsed back with |eval()|.
 
 			{expr} type	result ~
-			String		'string'
+			String		"string"
 			Number		123
 			Float		123.123456 or 1.123456e8 or
 					`str2float('inf')`

runtime/example_init.lua

@@ -100,3 +100,8 @@ vim.pack.add({
   -- Git integration
   'https://github.com/lewis6991/gitsigns.nvim',
 })
+
+require('fzf-lua').setup({ fzf_colors = true })
+require('mini.completion').setup {}
+require('quicker').setup {}
+require('gitsigns').setup {}

runtime/lua/vim/_core/editor.lua

@@ -1256,7 +1256,7 @@ end
 ---                              Defaults to "Nvim".
 ---@param backtrace   boolean|nil Prints backtrace. Defaults to true.
 ---
----@return string|nil # Deprecated message, or nil if no message was shown.
+---@return string|nil # Deprecation message, or nil if no message was shown.
 function vim.deprecate(name, alternative, version, plugin, backtrace)
   plugin = plugin or 'Nvim'
   if plugin == 'Nvim' then

runtime/lua/vim/_meta/vimfn.lua

@@ -9717,7 +9717,7 @@ function vim.fn.stridx(haystack, needle, start) end
 --- parsed back with |eval()|.
 ---
 ---   {expr} type  result ~
----   String    'string'
+---   String    "string"
 ---   Number    123
 ---   Float    123.123456 or 1.123456e8 or
 ---       `str2float('inf')`

runtime/lua/vim/lsp.lua

@@ -423,7 +423,11 @@ end
 
 --- Get LSP configs.
 ---
---- Note: Will eagerly evaluate config files in `'runtimepath'` if necessary.
+--- WARNING:
+--- - May eagerly (prematurely!) evaluate config files in 'runtimepath'.
+--- - Configs may be in a partial state if they have async properties such as `on_dir()`.
+---
+--- @since 14
 --- @param filter? vim.lsp.get_configs.Filter
 --- @return vim.lsp.Config[]: List of |vim.lsp.Config| objects
 function lsp.get_configs(filter)

runtime/lua/vim/treesitter/_meta/tsnode.lua

@@ -3,8 +3,8 @@
 error('Cannot require a meta file')
 
 --- @brief A "treesitter node" represents one specific element of the parsed contents of a buffer,
---- which can be captured by a |Query| for, e.g., highlighting. It is a |userdata| reference to an
---- object held by the treesitter library.
+--- which can be captured by a |treesitter-query| for, e.g., highlighting. It is a |userdata|
+--- reference to an object held by the treesitter library.
 ---
 --- An instance `TSNode` of a treesitter node supports the following methods.
 

runtime/lua/vim/ui.lua

@@ -322,7 +322,7 @@ do
   -- store progress events
   local progress_group, progress_autocmd = nil, nil
 
-  ---Initialize progress event listeners
+  --- Initialize Progress handlers.
   local function progress_init()
     progress_group = vim.api.nvim_create_augroup('nvim.ui.progress_status', { clear = true })
     progress_autocmd = vim.api.nvim_create_autocmd('Progress', {
@@ -333,12 +333,8 @@ do
         if not ev.data or not ev.data.id then
           return
         end
-        progress[ev.data.id] = {
-          id = ev.data.id,
-          title = ev.data.title,
-          status = ev.data.status,
-          percent = ev.data.percent or 0,
-        }
+        ev.data.percent = ev.data.percent or 0
+        progress[ev.data.id] = ev.data
 
         -- Clear finished items
         if
@@ -353,7 +349,7 @@ do
     })
   end
 
-  ---Return statusline text summarizing progress messages.
+  --- Gets a status description summarizing currently running progress messages.
   --- - If none: returns empty string
   --- - If one running item: "title: 42%"
   --- - If multiple running items: "Progress: N items AVG%"
@@ -379,11 +375,11 @@ do
     end
   end
 
-  --- Gets the status of currently running progress messages, in a format
-  --- convenient for inclusion in 'statusline'.
-  ---@return string formatted text of progress status for statusline
+  --- Gets a status description summarizing currently running progress messages.
+  --- Convenient for inclusion in 'statusline'.
+  ---
+  ---@return string # Progress status
   function M.progress_status()
-    -- Create progress event listener on first call
     if progress_autocmd == nil then
       progress_init()
     end

src/gen/gen_help_html.lua

@@ -117,10 +117,7 @@ local redirects = {
 
 -- TODO: These known invalid |links| require an update to the relevant docs.
 local exclude_invalid = {
-  ["'string'"] = 'vimeval.txt',
-  Query = 'treesitter.txt',
   matchit = 'vim_diff.txt',
-  ['set!'] = 'treesitter.txt',
 }
 
 -- False-positive "invalid URLs".

src/nvim/eval.lua

@@ -11713,7 +11713,7 @@ M.funcs = {
       parsed back with |eval()|.
 
       	{expr} type	result ~
-      	String		'string'
+      	String		"string"
       	Number		123
       	Float		123.123456 or 1.123456e8 or
       			`str2float('inf')`

src/nvim/message.c

@@ -362,6 +362,7 @@ static HlMessage format_progress_message(HlMessage hl_msg, MessageData *msg_data
 MsgID msg_multihl(MsgID id, HlMessage hl_msg, const char *kind, bool history, bool err,
                   MessageData *msg_data, bool *needs_msg_clear)
 {
+  // Message `id`:
   // - Nil: Generate a new Integer id.
   // - Integer: Existing id.
   // - String: User-defined id (new or existing).

src/nvim/path.c

@@ -2380,7 +2380,7 @@ static int path_to_absolute(const char *fname, char *buf, size_t len, int force)
     if (p == NULL) {
       p = strrchr(fname, '\\');
     }
-    if (p == NULL && ASCII_ISALPHA(fname[0]) && fname[1] == ':') {
+    if (p == NULL && ASCII_ISALPHA(fname[0]) && fname[1] == ':') {  // drive letter
       p = fname + 1;
     }
 #endif

test/functional/ex_cmds/menu_spec.lua

@@ -66,6 +66,7 @@ describe(':emenu', function()
     feed('itext<C-o>V')
     command('emenu PopUp.Cut')
     eq('', fn.getline(1))
+    eq('text\n', fn.getreg('"'))
     eq('', n.api.nvim_get_vvar('errmsg'))
   end)
 end)