docs: misc

runtime/doc/api.txt

@@ -1267,12 +1267,19 @@ nvim_open_term({buf}, {opts})                               *nvim_open_term()*
     be echoed directly by the terminal. This is useful to display ANSI
     terminal sequences returned as part of an RPC message, or similar.
 
-    Note: to directly initiate the terminal using the right size, display the
-    buffer in a configured window before calling this. For instance, for a
-    floating display, first create an empty buffer using |nvim_create_buf()|,
-    then display it using |nvim_open_win()|, and then call this function. Then
-    |nvim_chan_send()| can be called immediately to process sequences in a
-    virtual terminal having the intended size.
+    Note: |:ls| reports the buffer as "R" (running) until the channel is
+    closed. |chanclose()|
+
+    Note: To initialize the terminal size, display the buffer in a window
+    first. E.g. for a floating display,
+    1. Create an empty buffer using |nvim_create_buf()|.
+
+    2. Display it with |nvim_open_win()|.
+
+    3. Call nvim_open_term().
+
+    4. Then calling |nvim_chan_send()| will process sequences in a virtual
+       terminal with the intended size (defined by the window width/height).
 
     Example: this `TermHl` command can be used to display and highlight raw
     ANSI termcodes, so you can use Nvim as a "scrollback pager" (for terminals
@@ -1287,8 +1294,8 @@ nvim_open_term({buf}, {opts})                               *nvim_open_term()*
         Since: 0.5.0
 
     Parameters: ~
-      • {buf}   (`integer`) Buffer to use. Buffer contents (if any) will be
-                written to the PTY.
+      • {buf}   (`integer`) Buffer which displays the PTY output. The initial
+                buffer contents (if any) will be written to the PTY.
       • {opts}  (`vim.api.keyset.open_term`) Optional parameters.
                 • force_crlf: (boolean, default true) Convert "\n" to "\r\n".
                 • on_input: Lua callback for input sent, i e keypresses in

runtime/doc/windows.txt

@@ -1131,25 +1131,23 @@ list of buffers. |unlisted-buffer|
 			"[No Name]"	no file name specified
 
 		Indicators (chars in the same column are mutually exclusive):
-		u	an unlisted buffer (only displayed when [!] is used)
-			   |unlisted-buffer|
-		 %	the buffer in the current window
-		 #	the alternate buffer for ":e #" and CTRL-^
-		  a	an active buffer: it is loaded and visible
-		  h	a hidden buffer: It is loaded, but currently not
-			   displayed in a window |hidden-buffer|
-		   `-`	a buffer with 'modifiable' off
-		   =	a readonly buffer
-		   R	a terminal buffer with a running job
-		   F	a terminal buffer with a finished job
-		   ?    a terminal buffer without a job: `:terminal NONE`
-		    +	a modified buffer
-		    x   a buffer with read errors
+		u	|unlisted-buffer| (only displayed when [!] is used)
+		 %	buffer in the current window
+		 #	|alternate-file| buffer for |:e#| and |CTRL-^|
+		  a	an active buffer: loaded and visible
+		  h	|hidden-buffer|: loaded, but not displayed in a window
+		   `-`	'nomodifiable' buffer
+		   =	readonly buffer
+		   R	terminal buffer with a Running job (open channel)
+		   F	terminal buffer with a Finished job (closed channel)
+		   ?    terminal buffer without a job: `:terminal NONE`
+		    +	'modified' buffer
+		    x   buffer with read errors
 
 		[flags] can be a combination of the following characters,
 		which restrict the buffers to be listed:
 			+	modified buffers
-			`-`	buffers with 'modifiable' off
+			`-`	'nomodifiable' buffers
 			=	readonly buffers
 			a	active buffers
 			u	unlisted buffers (overrides the "!")
@@ -1157,8 +1155,8 @@ list of buffers. |unlisted-buffer|
 			x	buffers with a read error
 			%	current buffer
 			#	alternate buffer
-			R	terminal buffers with a running job
-			F	terminal buffers with a finished job
+			R	terminal buffers with a Running job
+			F	terminal buffers with a Finished job
 			t	show time last used and sort buffers
 		Combining flags means they are "and"ed together, e.g.:
 			h+	hidden buffers which are modified

runtime/lua/vim/_meta/api.gen.lua

@@ -1683,12 +1683,14 @@ function vim.api.nvim_open_tabpage(buf, enter, config) end
 --- will be echoed directly by the terminal. This is useful to display
 --- ANSI terminal sequences returned as part of an RPC message, or similar.
 ---
---- Note: to directly initiate the terminal using the right size, display the
---- buffer in a configured window before calling this. For instance, for a
---- floating display, first create an empty buffer using `nvim_create_buf()`,
---- then display it using `nvim_open_win()`, and then  call this function.
---- Then `nvim_chan_send()` can be called immediately to process sequences
---- in a virtual terminal having the intended size.
+--- Note: `:ls` reports the buffer as "R" (running) until the channel is closed. `chanclose()`
+---
+--- Note: To initialize the terminal size, display the buffer in a window first. E.g. for a floating display,
+--- 1. Create an empty buffer using `nvim_create_buf()`.
+--- 2. Display it with `nvim_open_win()`.
+--- 3. Call nvim_open_term().
+--- 4. Then calling `nvim_chan_send()` will process sequences in a virtual terminal with the
+---    intended size (defined by the window width/height).
 ---
 --- Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
 --- can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]()
@@ -1700,8 +1702,8 @@ function vim.api.nvim_open_tabpage(buf, enter, config) end
 --- end, { desc = 'Highlights ANSI termcodes in curbuf' })
 --- ```
 ---
---- @param buf integer Buffer to use. Buffer contents (if any) will be written
---- to the PTY.
+--- @param buf integer Buffer which displays the PTY output. The initial buffer contents (if any) will be
+--- written to the PTY.
 --- @param opts vim.api.keyset.open_term Optional parameters.
 --- - force_crlf: (boolean, default true) Convert "\n" to "\r\n".
 --- - on_input: Lua callback for input sent, i e keypresses in terminal

src/nvim/api/vim.c

@@ -1120,12 +1120,14 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
 /// will be echoed directly by the terminal. This is useful to display
 /// ANSI terminal sequences returned as part of an RPC message, or similar.
 ///
-/// Note: to directly initiate the terminal using the right size, display the
-/// buffer in a configured window before calling this. For instance, for a
-/// floating display, first create an empty buffer using |nvim_create_buf()|,
-/// then display it using |nvim_open_win()|, and then  call this function.
-/// Then |nvim_chan_send()| can be called immediately to process sequences
-/// in a virtual terminal having the intended size.
+/// Note: |:ls| reports the buffer as "R" (running) until the channel is closed. |chanclose()|
+///
+/// Note: To initialize the terminal size, display the buffer in a window first. E.g. for a floating display,
+/// 1. Create an empty buffer using |nvim_create_buf()|.
+/// 2. Display it with |nvim_open_win()|.
+/// 3. Call nvim_open_term().
+/// 4. Then calling |nvim_chan_send()| will process sequences in a virtual terminal with the
+///    intended size (defined by the window width/height).
 ///
 /// Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
 /// can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]()
@@ -1137,8 +1139,8 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
 /// end, { desc = 'Highlights ANSI termcodes in curbuf' })
 /// ```
 ///
-/// @param buf Buffer to use. Buffer contents (if any) will be written
-///               to the PTY.
+/// @param buf Buffer which displays the PTY output. The initial buffer contents (if any) will be
+///            written to the PTY.
 /// @param opts   Optional parameters.
 ///          - force_crlf: (boolean, default true) Convert "\n" to "\r\n".
 ///          - on_input: Lua callback for input sent, i e keypresses in terminal

src/nvim/path.c

@@ -156,10 +156,8 @@ char *path_tail_with_sep(char *fname)
 /// - "\"path/foo bar/bash\" --login" => "bash"
 /// - "\"path/foo\\\" bar/bash\" --login" => "bash"
 ///
-/// @param[in]  invocation Program invocation string.
-/// @param[out] len Stores the length of the executable name.
-///
-/// @post if `len` is not null, stores the length of the executable name.
+/// @param[in]  invocation Program invocation of the form: "path/to/exe [args]".
+/// @param[out] len Stores the length of the executable name, if not NULL.
 ///
 /// @return The position of the last path separator + 1.
 const char *invocation_path_tail(const char *invocation, size_t *len)

test/functional/options/shell_spec.lua

@@ -7,7 +7,7 @@ local skip = t.skip
 local api = n.api
 local clear = n.clear
 
-describe('applies sensible default options for different shells #28384', function()
+describe("'shell…' option defaults based on $SHELL #28384", function()
   ---@param sh string
   ---@param shcf string
   ---@param sp string
@@ -69,7 +69,7 @@ describe('applies sensible default options for different shells #28384', functio
     )
   end)
 
-  it('even if the path contains spaces', function()
+  it('if the path contains spaces', function()
     clear {
       env = { SHELL = ('%s/foo bar/bash'):format(n.nvim_dir) },
     }