docs: various clarifications (#24876)

10 files changed, 43 insertions, 41 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 67a6b8df9c..9510f12045 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -8316,15 +8316,15 @@ type({expr})                                                            *type()*
 		The result is a Number representing the type of {expr}.
 		Instead of using the number directly, it is better to use the
 		v:t_ variable that has the value:
-		        Number:     0 (|v:t_number|)
-			String:     1 (|v:t_string|)
-			Funcref:    2 (|v:t_func|)
-			List:       3 (|v:t_list|)
-			Dictionary: 4 (|v:t_dict|)
-			Float:      5 (|v:t_float|)
-			Boolean:    6 (|v:true| and |v:false|)
-			Null:       7 (|v:null|)
-			Blob:      10 (|v:t_blob|)
+			Number:	    0  |v:t_number|
+			String:	    1  |v:t_string|
+			Funcref:    2  |v:t_func|
+			List:	    3  |v:t_list|
+			Dictionary: 4  |v:t_dict|
+			Float:	    5  |v:t_float|
+			Boolean:    6  |v:t_bool| (|v:false| and |v:true|)
+			Null:	    7  (|v:null|)
+			Blob:	   10  |v:t_blob|
 		For backward compatibility, this method can be used: >vim
 			if type(myvar) == type(0) | endif
 			if type(myvar) == type("") | endif
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index b4ca88251e..39eb530c24 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -979,12 +979,12 @@ vim.str_utf_end({str}, {index})                            *vim.str_utf_end()*
 
     Examples: >lua
 
-     -- The character 'æ' are equal to the bytes '\xc3\xa6' (using UTF-8)
+     -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8)
 
      -- Returns 0 because the index is pointing at the last byte of a character
      vim.str_utf_end('æ', 2)
 
-     -- Returns 1 because the index is pointing at the second last byte of a character
+     -- Returns 1 because the index is pointing at the penultimate byte of a character
      vim.str_utf_end('æ', 1)
 <
 
@@ -1016,7 +1016,7 @@ vim.str_utf_start({str}, {index})                        *vim.str_utf_start()*
 
     Examples: >lua
 
-     -- The character 'æ' are equal to the bytes '\xc3\xa6' (using UTF-8)
+     -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8)
 
      -- Returns 0 because the index is pointing at the first byte of a character
      vim.str_utf_start('æ', 1)
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index eea9f2cf4b..e2ca9c1992 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -4259,8 +4259,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 'mousescroll'		string	(default "ver:3,hor:6")
 			global
 	This option controls the number of lines / columns to scroll by when
-	scrolling with a mouse. The option is a comma separated list of parts.
-	Each part consists of a direction and a count as follows:
+	scrolling with a mouse wheel (|scroll-mouse-wheel|). The option is
+	a comma-separated list. Each part consists of a direction and a count
+	as follows:
 		direction:count,direction:count
 	Direction is one of either "hor" or "ver". "hor" controls horizontal
 	scrolling and "ver" controls vertical scrolling. Count sets the amount
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index a5508bdc04..d7b76a803c 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -132,7 +132,7 @@ function vim.str_utf_pos(str) end
 ---
 --- Examples:
 --- <pre>lua
---- -- The character 'æ' are equal to the bytes '\xc3\xa6' (using UTF-8)
+--- -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8)
 ---
 --- -- Returns 0 because the index is pointing at the first byte of a character
 --- vim.str_utf_start('æ', 1)
@@ -151,12 +151,12 @@ function vim.str_utf_start(str, index) end
 ---
 --- Examples:
 --- <pre>lua
---- -- The character 'æ' are equal to the bytes '\xc3\xa6' (using UTF-8)
+--- -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8)
 ---
 --- -- Returns 0 because the index is pointing at the last byte of a character
 --- vim.str_utf_end('æ', 2)
 ---
---- -- Returns 1 because the index is pointing at the second last byte of a character
+--- -- Returns 1 because the index is pointing at the penultimate byte of a character
 --- vim.str_utf_end('æ', 1)
 --- </pre>
 ---
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 8edb87df91..4fb3141df0 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -4323,8 +4323,9 @@ vim.go.mousemoveevent = vim.o.mousemoveevent
 vim.go.mousemev = vim.go.mousemoveevent
 
 --- This option controls the number of lines / columns to scroll by when
---- scrolling with a mouse. The option is a comma separated list of parts.
---- Each part consists of a direction and a count as follows:
+--- scrolling with a mouse wheel (`scroll-mouse-wheel`). The option is
+--- a comma-separated list. Each part consists of a direction and a count
+--- as follows:
 --- 	direction:count,direction:count
 --- Direction is one of either "hor" or "ver". "hor" controls horizontal
 --- scrolling and "ver" controls vertical scrolling. Count sets the amount
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 0ac8985274..ebd74046ce 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -9878,15 +9878,15 @@ function vim.fn.trunc(expr) end
 --- The result is a Number representing the type of {expr}.
 --- Instead of using the number directly, it is better to use the
 --- v:t_ variable that has the value:
----         Number:     0 (|v:t_number|)
----   String:     1 (|v:t_string|)
----   Funcref:    2 (|v:t_func|)
----   List:       3 (|v:t_list|)
----   Dictionary: 4 (|v:t_dict|)
----   Float:      5 (|v:t_float|)
----   Boolean:    6 (|v:true| and |v:false|)
----   Null:       7 (|v:null|)
----   Blob:      10 (|v:t_blob|)
+---   Number:      0  |v:t_number|
+---   String:      1  |v:t_string|
+---   Funcref:    2  |v:t_func|
+---   List:      3  |v:t_list|
+---   Dictionary: 4  |v:t_dict|
+---   Float:      5  |v:t_float|
+---   Boolean:    6  |v:t_bool| (|v:false| and |v:true|)
+---   Null:      7  (|v:null|)
+---   Blob:     10  |v:t_blob|
 --- For backward compatibility, this method can be used: >vim
 ---   if type(myvar) == type(0) | endif
 ---   if type(myvar) == type("") | endif
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index d5dff3d70d..bb642b97f8 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -11824,15 +11824,15 @@ M.funcs = {
       The result is a Number representing the type of {expr}.
       Instead of using the number directly, it is better to use the
       v:t_ variable that has the value:
-              Number:     0 (|v:t_number|)
-      	String:     1 (|v:t_string|)
-      	Funcref:    2 (|v:t_func|)
-      	List:       3 (|v:t_list|)
-      	Dictionary: 4 (|v:t_dict|)
-      	Float:      5 (|v:t_float|)
-      	Boolean:    6 (|v:true| and |v:false|)
-      	Null:       7 (|v:null|)
-      	Blob:      10 (|v:t_blob|)
+      	Number:	    0  |v:t_number|
+      	String:	    1  |v:t_string|
+      	Funcref:    2  |v:t_func|
+      	List:	    3  |v:t_list|
+      	Dictionary: 4  |v:t_dict|
+      	Float:	    5  |v:t_float|
+      	Boolean:    6  |v:t_bool| (|v:false| and |v:true|)
+      	Null:	    7  (|v:null|)
+      	Blob:	   10  |v:t_blob|
       For backward compatibility, this method can be used: >vim
       	if type(myvar) == type(0) | endif
       	if type(myvar) == type("") | endif
diff --git a/src/nvim/normal.c b/src/nvim/normal.c
index 20680df144..1a220bc962 100644
--- a/src/nvim/normal.c
+++ b/src/nvim/normal.c
@@ -1411,7 +1411,6 @@ static int normal_check(VimState *state)
   }
   quit_more = false;
 
-  // it's not safe unless normal_check_safe_state() is called
   state_no_longer_safe(NULL);
 
   // If skip redraw is set (for ":" in wait_return()), don't redraw now.
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index a565329eac..b774df476f 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -5500,8 +5500,9 @@ return {
       defaults = { if_true = 'ver:3,hor:6' },
       desc = [=[
         This option controls the number of lines / columns to scroll by when
-        scrolling with a mouse. The option is a comma separated list of parts.
-        Each part consists of a direction and a count as follows:
+        scrolling with a mouse wheel (|scroll-mouse-wheel|). The option is
+        a comma-separated list. Each part consists of a direction and a count
+        as follows:
         	direction:count,direction:count
         Direction is one of either "hor" or "ver". "hor" controls horizontal
         scrolling and "ver" controls vertical scrolling. Count sets the amount
diff --git a/src/nvim/plines.c b/src/nvim/plines.c
index 8ecefc805a..be6bcd22ae 100644
--- a/src/nvim/plines.c
+++ b/src/nvim/plines.c
@@ -726,7 +726,7 @@ void getvcols(win_T *wp, pos_T *pos1, pos_T *pos2, colnr_T *left, colnr_T *right
 /// Functions calculating vertical size of text when displayed inside a window.
 /// Calls horizontal size functions defined above.
 
-/// Check the there may be filler inlines anywhere in window "wp"
+/// Check if there may be filler inlines anywhere in window "wp".
 bool win_may_fill(win_T *wp)
 {
   return (wp->w_p_diff && diffopt_filler()) || wp->w_buffer->b_virt_line_blocks;