docs: misc #38532

Close #38431
Close #38521
Close #38530

Co-authored-by: tayheau <thopsore@pasteur.fr>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>
Co-authored-by: Olivia Kinnear <git@superatomic.dev>

runtime/doc/cmdline.txt

@@ -612,6 +612,7 @@ followed by another Vim command:
     :ldo
     :lfdo
     :lhelpgrep
+    :lsp
     :make
     :normal
     :perlfile

runtime/doc/gui.txt

@@ -93,7 +93,6 @@ Restart Nvim
 Connect UI to a different server
 
                                                 *:connect*
-
 :connect {address}
                 Detaches the UI from the server it is currently attached to
                 and attaches it to the server at {address} instead.

runtime/doc/lsp.txt

@@ -717,7 +717,7 @@ LspProgress                                                       *LspProgress*
         vim.api.nvim_create_autocmd('LspProgress', { buffer = buf, callback = function(ev)
             local value = ev.data.params.value
             vim.api.nvim_echo({ { value.message or 'done' } }, false, {
-              id = ev.data.id,
+              id = 'lsp.' .. ev.data.client_id,
               kind = 'progress',
               source = 'vim.lsp',
               title = value.title,
@@ -2462,7 +2462,7 @@ The `vim.lsp.log` module provides logging for the Nvim LSP client.
 When debugging language servers, it is helpful to enable extra-verbose logging
 of the LSP client RPC events. Example: >lua
     vim.lsp.log.set_level 'trace'
-    require('vim.lsp.log').set_format_func(vim.inspect)
+    vim.lsp.log.set_format_func(vim.inspect)
 <
 
 Then try to run the language server, and open the log with: >vim

runtime/doc/lua.txt

@@ -4216,9 +4216,9 @@ vim.net.request({url}, {opts}, {on_response})              *vim.net.request()*
 ==============================================================================
 Lua module: vim.pos                                                  *vim.pos*
 
-EXPERIMENTAL: This API may change in the future. Its semantics are not yet
-finalized. Subscribe to https://github.com/neovim/neovim/issues/25509 to stay
-updated or contribute to its development.
+EXPERIMENTAL: This API is unstable, do not use it. Its semantics are not yet
+finalized. Subscribe to this issue to stay updated:
+https://github.com/neovim/neovim/issues/25509
 
 Provides operations to compare, calculate, and convert positions represented
 by |vim.Pos| objects.
@@ -4345,20 +4345,22 @@ Pos:to_lsp({pos}, {position_encoding})                          *Pos:to_lsp()*
 ==============================================================================
 Lua module: vim.range                                              *vim.range*
 
-EXPERIMENTAL: This API may change in the future. Its semantics are not yet
-finalized. Subscribe to https://github.com/neovim/neovim/issues/25509 to stay
-updated or contribute to its development.
+EXPERIMENTAL: This API is unstable, do not use it. Its semantics are not yet
+finalized. Subscribe to this issue to stay updated:
+https://github.com/neovim/neovim/issues/25509
 
 Provides operations to compare, calculate, and convert ranges represented by
 |vim.Range| objects.
 
 
 *vim.Range*
-    Represents a well-defined range.
+    Represents a range. Call `vim.range()` to create a new range.
 
-    A |vim.Range| object contains a {start} and a {end_} position(see
-    |vim.Pos|). Note that the {end_} position is exclusive. To create a new
-    |vim.Range| object, call `vim.range()`.
+    A range contains a start and end position (see |vim.Pos|). The end
+    position is exclusive. Positions must have the same optional fields.
+
+    May include optional fields that enable additional capabilities, such as
+    format conversions.
 
     Example: >lua
         local pos1 = vim.pos(3, 5)
@@ -4379,10 +4381,6 @@ Provides operations to compare, calculate, and convert ranges represented by
         end
 <
 
-    It may include optional fields that enable additional capabilities, such
-    as format conversions. Note that the {start} and {end_} positions need to
-    have the same optional fields.
-
     Fields: ~
       • {start_row}   (`integer`) 0-based byte index.
       • {start_col}   (`integer`) 0-based byte index.

runtime/doc/news.txt

@@ -137,7 +137,7 @@ DEFAULTS
   was implemented as an internal C routine).
 • Default 'statusline' shows:
   • |vim.diagnostic.status()|
-  • |vim.ui.progress_status()
+  • |vim.ui.progress_status()|
   • :terminal exit code
 • Project-local configuration ('exrc') is also loaded from parent directories.
   Unset 'exrc' to stop further search.

runtime/lua/vim/lsp/log.lua

@@ -5,7 +5,7 @@
 --- RPC events. Example:
 --- ```lua
 --- vim.lsp.log.set_level 'trace'
---- require('vim.lsp.log').set_format_func(vim.inspect)
+--- vim.lsp.log.set_format_func(vim.inspect)
 --- ```
 ---
 --- Then try to run the language server, and open the log with:

runtime/lua/vim/pos.lua

@@ -1,8 +1,7 @@
 ---@brief
 ---
---- EXPERIMENTAL: This API may change in the future. Its semantics are not yet finalized.
---- Subscribe to https://github.com/neovim/neovim/issues/25509
---- to stay updated or contribute to its development.
+--- EXPERIMENTAL: This API is unstable, do not use it. Its semantics are not yet finalized.
+--- Subscribe to this issue to stay updated: https://github.com/neovim/neovim/issues/25509
 ---
 --- Provides operations to compare, calculate, and convert positions represented by |vim.Pos|
 --- objects.

runtime/lua/vim/range.lua

@@ -1,8 +1,7 @@
 ---@brief
 ---
---- EXPERIMENTAL: This API may change in the future. Its semantics are not yet finalized.
---- Subscribe to https://github.com/neovim/neovim/issues/25509
---- to stay updated or contribute to its development.
+--- EXPERIMENTAL: This API is unstable, do not use it. Its semantics are not yet finalized.
+--- Subscribe to this issue to stay updated: https://github.com/neovim/neovim/issues/25509
 ---
 --- Provides operations to compare, calculate, and convert ranges represented by |vim.Range|
 --- objects.
@@ -10,11 +9,12 @@
 local validate = vim.validate
 local api = vim.api
 
---- Represents a well-defined range.
+--- Represents a range. Call `vim.range()` to create a new range.
 ---
---- A |vim.Range| object contains a {start} and a {end_} position(see |vim.Pos|).
---- Note that the {end_} position is exclusive.
---- To create a new |vim.Range| object, call `vim.range()`.
+--- A range contains a start and end position (see |vim.Pos|). The end position is exclusive.
+--- Positions must have the same optional fields.
+---
+--- May include optional fields that enable additional capabilities, such as format conversions.
 ---
 --- Example:
 --- ```lua
@@ -36,10 +36,6 @@ local api = vim.api
 --- end
 --- ```
 ---
---- It may include optional fields that enable additional capabilities,
---- such as format conversions. Note that the {start} and {end_} positions
---- need to have the same optional fields.
----
 ---@class vim.Range
 ---@field start_row integer 0-based byte index.
 ---@field start_col integer 0-based byte index.

src/nvim/option.c

@@ -11,6 +11,7 @@
 //   - For a buffer string option, add code to check_buf_options().
 // - If it's a numeric option, add any necessary bounds checks to check_num_option_bounds().
 // - If it's a list of flags, add some code in do_set(), search for WW_ALL.
+// - If it depends on options values, add it to didset_string_options().
 // - Add documentation! "desc" in options.lua, and any other related places.
 // - Add an entry in runtime/scripts/optwin.lua.
 

src/nvim/ui_client.c

@@ -275,6 +275,7 @@ void ui_client_event_raw_line(GridLineEvent *g)
                (const schar_T *)grid_line_buf_char, grid_line_buf_attr);
 }
 
+/// Handles the "connect" ui-event.
 void ui_client_event_connect(Array args)
 {
   if (args.size < 1 || args.items[0].type != kObjectTypeString) {
@@ -312,11 +313,12 @@ static void channel_connect_event(void **argv)
   xfree(server_addr);
 }
 
-/// When a "restart" UI event is received, its arguments are saved here when
+/// When a "restart" ui-event is received, its arguments are saved here when
 /// waiting for the server to exit.
 static Array restart_args = ARRAY_DICT_INIT;
 static bool restart_pending = false;
 
+/// Handles the "restart" ui-event.
 void ui_client_event_restart(Array args)
 {
   // NB: don't send nvim_ui_detach to server, as it may have already exited.
@@ -328,7 +330,7 @@ void ui_client_event_restart(Array args)
   restart_pending = true;
 }
 
-/// Called when the current server has exited.
+/// Called during "restart" when the old server just exited.
 void ui_client_attach_to_restarted_server(void)
 {
   if (!restart_pending) {
@@ -362,6 +364,7 @@ cleanup:
   restart_args = (Array)ARRAY_DICT_INIT;
 }
 
+/// Handles the "error_exit" ui-event.
 void ui_client_event_error_exit(Array args)
 {
   if (args.size < 1