docs: fix typos (#20150)

Co-authored-by: Miguel Carneiro <mcarneiromorenas@gmail.com>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: Raphael <glephunter@gmail.com>
Co-authored-by: C.D. MacEachern <craig.daniel.maceachern@gmail.com>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>

21 files changed, 63 insertions, 58 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index ec16d5c650..ce59f5ad52 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3435,8 +3435,8 @@ nvim_ui_detach()                                            *nvim_ui_detach()*
 
                                                     *nvim_ui_pum_set_bounds()*
 nvim_ui_pum_set_bounds({width}, {height}, {row}, {col})
-    Tells Nvim the geometry of the popumenu, to align floating windows with an
-    external popup menu.
+    Tells Nvim the geometry of the popupmenu, to align floating windows with
+    an external popup menu.
 
     Note that this method is not to be confused with
     |nvim_ui_pum_set_height()|, which sets the number of visible items in the
@@ -3455,7 +3455,7 @@ nvim_ui_pum_set_bounds({width}, {height}, {row}, {col})
         {col}     Popupmenu height.
 
 nvim_ui_pum_set_height({height})                    *nvim_ui_pum_set_height()*
-    Tells Nvim the number of elements displaying in the popumenu, to decide
+    Tells Nvim the number of elements displaying in the popupmenu, to decide
     <PageUp> and <PageDown> movement.
 
     Attributes: ~
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 77b85406b9..735116f9a0 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1131,13 +1131,14 @@ chdir({dir})						*chdir()*
 			  directory (|:tcd|) then changes the tabpage local
 			  directory.
 			- Otherwise, changes the global directory.
+		{dir} must be a String.
 		If successful, returns the previous working directory.  Pass
 		this to another chdir() to restore the directory.
 		On failure, returns an empty string.
 
 		Example: >
 			let save_dir = chdir(newdir)
-			if save_dir
+			if save_dir != ""
 			   " ... do some work
 			   call chdir(save_dir)
 			endif
@@ -3240,7 +3241,7 @@ getloclist({nr} [, {what}])				*getloclist()*
 		In addition to the items supported by |getqflist()| in {what},
 		the following item is supported by |getloclist()|:
 
-			filewinid 	id of the window used to display files
+			filewinid	id of the window used to display files
 					from the location list. This field is
 					applicable only when called from a
 					location list window. See
@@ -6069,6 +6070,8 @@ rand([{expr}])						*rand()*
 							*readdir()*
 readdir({directory} [, {expr}])
 		Return a list with file and directory names in {directory}.
+		You can also use |glob()| if you don't need to do complicated
+		things, such as limiting the number of matches.
 
 		When {expr} is omitted all entries are included.
 		When {expr} is given, it is evaluated to check what to do:
@@ -8303,12 +8306,12 @@ synconcealed({lnum}, {col})				*synconcealed()*
 		   the text is "123456" and both "23" and "45" are concealed
 		   and replaced by the character "X", then:
 			call			returns ~
-		   	synconcealed(lnum, 1)   [0, '', 0]
-		   	synconcealed(lnum, 2)   [1, 'X', 1]
-		   	synconcealed(lnum, 3)   [1, 'X', 1]
-		   	synconcealed(lnum, 4)   [1, 'X', 2]
-		   	synconcealed(lnum, 5)   [1, 'X', 2]
-		   	synconcealed(lnum, 6)   [0, '', 0]
+			synconcealed(lnum, 1)   [0, '', 0]
+			synconcealed(lnum, 2)   [1, 'X', 1]
+			synconcealed(lnum, 3)   [1, 'X', 1]
+			synconcealed(lnum, 4)   [1, 'X', 2]
+			synconcealed(lnum, 5)   [1, 'X', 2]
+			synconcealed(lnum, 6)   [0, '', 0]
 
 
 synstack({lnum}, {col})					*synstack()*
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 78254c6f2b..ada7b93f7c 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -296,7 +296,7 @@ EVENTS                                                  *diagnostic-events*
 
                                                         *DiagnosticChanged*
 DiagnosticChanged       After diagnostics have changed. When used from Lua,
-                        the new diagnostics are passed to the autocmcd
+                        the new diagnostics are passed to the autocmd
                         callback in the "data" table.
 
 Example: >
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 3e068e3b4e..bfaa3b12e8 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -457,7 +457,7 @@ String automatically.  Thus the String '4' and the number 4 will find the same
 entry.  Note that the String '04' and the Number 04 are different, since the
 Number will be converted to the String '4', leading zeros are dropped.  The
 empty string can also be used as a key.
-						*literal-Dict*
+						*literal-Dict* *#{}*
 To avoid having to put quotes around every key the #{} form can be used.  This
 does require the key to consist only of ASCII letters, digits, '-' and '_'.
 Example: >
@@ -681,7 +681,7 @@ similar to -1. >
 	:let shortblob = myblob[2:2]	" Blob with one byte: 0z22
 	:let otherblob = myblob[:]	" make a copy of the Blob
 
-If the first index is beyond the last byte of the Blob or the second byte is
+If the first index is beyond the last byte of the Blob or the second index is
 before the first index, the result is an empty Blob.  There is no error
 message.
 
@@ -704,8 +704,8 @@ The length of the replaced bytes must be exactly the same as the value
 provided. *E972*
 
 To change part of a blob you can specify the first and last byte to be
-modified.  The value must at least have the number of bytes in the range: >
-	:let blob[3:5] = [3, 4, 5]
+modified.  The value must have the same number of bytes in the range: >
+	:let blob[3:5] = 0z334455
 
 You can also use the functions |add()|, |remove()| and |insert()|.
 
@@ -1228,7 +1228,10 @@ And NOT: >
 	\ ->map(mapexpr)
 	\ ->sort()
 	\ ->join()
-<
+
+When using the lambda form there must be no white space between the } and the
+(.
+
 
 							*expr9*
 number
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index f4ef8e65c4..9ea963c812 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -1126,7 +1126,8 @@ that contains the List.  The Dict can have these items:
 			leading text is changed.
 Other items are ignored.
 
-For acting upon end of completion, see the |CompleteDone| autocommand event.
+For acting upon end of completion, see the |CompleteDonePre| and
+|CompleteDone| autocommand event.
 
 For example, the function can contain this: >
 	let matches = ... list of words ...
diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index 511b1bd7b2..77b6b83289 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -831,12 +831,12 @@ deletes the lines from the cursor position to mark 't'.  Hint: Use mark 't' for
 Top, 'b' for Bottom, etc..  Lowercase marks are restored when using undo and
 redo.
 
-Uppercase marks 'A to 'Z include the file name.
-You can use them to jump from file to file.  You can only use an uppercase
-mark with an operator if the mark is in the current file.  The line number of
-the mark remains correct, even if you insert/delete lines or edit another file
-for a moment.  When the 'shada' option is not empty, uppercase marks are
-kept in the .shada file.  See |shada-file-marks|.
+Uppercase marks 'A to 'Z include the file name.  You can use them to jump from
+file to file.  You can only use an uppercase mark with an operator if the mark
+is in the current file.  The line number of the mark remains correct, even if
+you insert/delete lines or edit another file for a moment.  When the 'shada'
+option is not empty, uppercase marks are kept in the .shada file.  See
+|shada-file-marks|.
 
 Numbered marks '0 to '9 are quite different.  They can not be set directly.
 They are only present when using a shada file |shada-file|.  Basically '0
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index e5ad61062f..c1a0836f5b 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6748,11 +6748,11 @@ A jump table for the options with a short description can be found at |Q_op|.
 	final value applying to all subsequent tabs.
 
 	For example, when editing assembly language files where statements
-	start in the 8th column and comments in the 40th, it may be useful
+	start in the 9th column and comments in the 41st, it may be useful
 	to use the following: >
 		:set varsofttabstop=8,32,8
-<	This will set soft tabstops at the 8th and 40th columns, and at every
-	8th column thereafter.
+<	This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more
+	for every column thereafter.
 
 	Note that the value of |'softtabstop'| will be ignored while
 	'varsofttabstop' is set.
diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt
index cc36e7186c..8a6437fdc8 100644
--- a/runtime/doc/pi_health.txt
+++ b/runtime/doc/pi_health.txt
@@ -75,7 +75,7 @@ vim.health.report_error({msg} [, {advice}])             *vim.health.report_error
 Create a healthcheck                                    *health-dev*
 
 Healthchecks are functions that check the user environment, configuration, or
-any other prerequisities that a plugin cares about. Nvim ships with
+any other prerequisites that a plugin cares about. Nvim ships with
 healthchecks in:
         - $VIMRUNTIME/autoload/health/
         - $VIMRUNTIME/lua/vim/lsp/health.lua
diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt
index 80110211f9..924a6d4743 100644
--- a/runtime/doc/quickfix.txt
+++ b/runtime/doc/quickfix.txt
@@ -916,7 +916,7 @@ To get the number of the current list in the stack: >
 			   screen).
 			5. The errorfile is read using 'errorformat'.
 			6. All relevant |QuickFixCmdPost| autocommands are
-			   executed. See example below.
+			   executed.  See example below.
 			7. If [!] is not given the first error is jumped to.
 			8. The errorfile is deleted.
 			9. You can now move through the errors with commands
@@ -1939,7 +1939,7 @@ list window is:
 The values displayed in each line correspond to the "bufnr", "lnum", "col" and
 "text" fields returned by the |getqflist()| function.
 
-For some quickfix/location lists, the displayed text need to be customized.
+For some quickfix/location lists, the displayed text needs to be customized.
 For example, if only the filename is present for a quickfix entry, then the
 two "|" field separator characters after the filename are not needed.  Another
 use case is to customize the path displayed for a filename. By default, the
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 1368814952..83f19db4a9 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -2057,7 +2057,7 @@ The g:lisp_rainbow option provides 10 levels of individual colorization for
 the parentheses and backquoted parentheses.  Because of the quantity of
 colorization levels, unlike non-rainbow highlighting, the rainbow mode
 specifies its highlighting using ctermfg and guifg, thereby bypassing the
-usual colorscheme control using standard highlighting groups.  The actual
+usual color scheme control using standard highlighting groups.  The actual
 highlighting used depends on the dark/bright setting  (see |'bg'|).
 
 
@@ -4838,7 +4838,7 @@ in their own color.
 
 			To customize a color scheme use another name, e.g.
 			"~/.config/nvim/colors/mine.vim", and use `:runtime` to
-			load the original colorscheme: >
+			load the original color scheme: >
 				runtime colors/evening.vim
 				hi Statement ctermfg=Blue guifg=Blue
 
@@ -4846,7 +4846,7 @@ in their own color.
 			|ColorSchemePre| autocommand event is triggered.
 			After the color scheme has been loaded the
 			|ColorScheme| autocommand event is triggered.
-			For info about writing a colorscheme file: >
+			For info about writing a color scheme file: >
 				:edit $VIMRUNTIME/colors/README.txt
 
 :hi[ghlight]		List all the current highlight groups that have
@@ -5016,7 +5016,7 @@ ctermbg={color-nr}				*ctermbg*
 	explicitly.  This causes the highlight groups that depend on
 	'background' to change!  This means you should set the colors for
 	Normal first, before setting other colors.
-	When a colorscheme is being used, changing 'background' causes it to
+	When a color scheme is being used, changing 'background' causes it to
 	be reloaded, which may reset all colors (including Normal).  First
 	delete the "g:colors_name" variable when you don't want this.
 
diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt
index 9197710819..49b2773253 100644
--- a/runtime/doc/tabpage.txt
+++ b/runtime/doc/tabpage.txt
@@ -186,8 +186,8 @@ gt					*i_CTRL-<PageDown>* *i_<C-PageDown>*
 		    :+2tabnext	" go to the two next tab page
 		    :1tabnext	" go to the first tab page
 		    :$tabnext	" go to the last tab page
-		    :tabnext #  " go to the last accessed tab page
 		    :tabnext $	" as above
+		    :tabnext #  " go to the last accessed tab page
 		    :tabnext -	" go to the previous tab page
 		    :tabnext -1	" as above
 		    :tabnext +	" go to the next tab page
diff --git a/runtime/doc/userfunc.txt b/runtime/doc/userfunc.txt
index 32c5b0b671..5462fa952c 100644
--- a/runtime/doc/userfunc.txt
+++ b/runtime/doc/userfunc.txt
@@ -214,7 +214,7 @@ It is allowed to define another function inside a function body.
 You can provide default values for positional named arguments.  This makes
 them optional for function calls.  When a positional argument is not
 specified at a call, the default expression is used to initialize it.
-This only works for functions declared with |:function|, not for
+This only works for functions declared with `:function`, not for
 lambda expressions |expr-lambda|.
 
 Example: >
diff --git a/runtime/doc/usr_22.txt b/runtime/doc/usr_22.txt
index f53d578456..539bda3980 100644
--- a/runtime/doc/usr_22.txt
+++ b/runtime/doc/usr_22.txt
@@ -220,7 +220,7 @@ a tab page share this directory except for windows with a window-local
 directory. Any new windows opened in this tab page will use this directory as
 the current working directory. Using a `:cd` command in a tab page will not
 change the working directory of tab pages which have a tab local directory.
-When the global working directory is changed using the ":cd" command in a tab
+When the global working directory is changed using the `:cd` command in a tab
 page, it will also change the current tab page working directory.
 
 
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index adb5130a53..4e7ec00148 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1016,6 +1016,7 @@ Testing:				    *test-functions*
 	assert_beeps()		assert that a command beeps
 	assert_nobeep()		assert that a command does not cause a beep
 	assert_fails()		assert that a command fails
+	assert_report()		report a test failure
 
 Timers:						*timer-functions*
 	timer_start()		create a timer
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index 6386e4ace1..3dc718a68f 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -148,7 +148,7 @@ CTRL-W CTRL-S						*CTRL-W_CTRL-S*
 		Note: CTRL-S does not work on all terminals and might block
 		further input, use CTRL-Q to get going again.
 		Also see |++opt| and |+cmd|.
-							*E242*
+							*E242* *E1159*
 		Be careful when splitting a window in an autocommand, it may
 		mess up the window layout if this happens while making other
 		window layout changes.
@@ -291,9 +291,8 @@ Closing a window
 :{count}q[uit]						*:count_quit*
 CTRL-W q						*CTRL-W_q*
 CTRL-W CTRL-Q						*CTRL-W_CTRL-Q*
-		Without {count}: Quit the current window. If {count} is
-		given quit the {count} window
-
+		Without {count}: Quit the current window.  If {count} is
+		given quit the {count} window.
 							*edit-window*
 		When quitting the last edit window (not counting help or
 		preview windows), exit Vim.
@@ -352,7 +351,7 @@ CTRL-W CTRL-C						*CTRL-W_CTRL-C*
 		window, but that does not work, because the CTRL-C cancels the
 		command.
 
-                                                                *:hide*
+							*:hide*
 :hid[e]
 :{count}hid[e]
 		Without {count}: Quit the current window, unless it is the
@@ -751,6 +750,7 @@ can also get to them with the buffer list commands, like ":bnext".
 			the current window.
 			{cmd} can contain '|' to concatenate several commands.
 			{cmd} must not open or close windows or reorder them.
+
 			Also see |:tabdo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|,
 			|:cfdo| and |:lfdo|.
 
@@ -778,6 +778,7 @@ can also get to them with the buffer list commands, like ":bnext".
 			autocommand event is disabled by adding it to
 			'eventignore'.  This considerably speeds up editing
 			each buffer.
+
 			Also see |:tabdo|, |:argdo|, |:windo|, |:cdo|, |:ldo|,
 			|:cfdo| and |:lfdo|.
 
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index 45c20d07e1..e6d8cb2fdb 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -453,7 +453,7 @@ void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width, I
   }
 }
 
-/// Tells Nvim the number of elements displaying in the popumenu, to decide
+/// Tells Nvim the number of elements displaying in the popupmenu, to decide
 /// <PageUp> and <PageDown> movement.
 ///
 /// @param channel_id
@@ -483,7 +483,7 @@ void nvim_ui_pum_set_height(uint64_t channel_id, Integer height, Error *err)
   ui->pum_nlines = (int)height;
 }
 
-/// Tells Nvim the geometry of the popumenu, to align floating windows with an
+/// Tells Nvim the geometry of the popupmenu, to align floating windows with an
 /// external popup menu.
 ///
 /// Note that this method is not to be confused with |nvim_ui_pum_set_height()|,
diff --git a/src/nvim/buffer_defs.h b/src/nvim/buffer_defs.h
index c18a8209cf..a8834b85aa 100644
--- a/src/nvim/buffer_defs.h
+++ b/src/nvim/buffer_defs.h
@@ -618,7 +618,7 @@ struct file_buffer {
   bool b_u_synced;              // entry lists are synced
   long b_u_seq_last;            // last used undo sequence number
   long b_u_save_nr_last;        // counter for last file write
-  long b_u_seq_cur;             // hu_seq of header below which we are now
+  long b_u_seq_cur;             // uh_seq of header below which we are now
   time_t b_u_time_cur;          // uh_time of header below which we are now
   long b_u_save_nr_cur;         // file write nr after which we are now
 
diff --git a/src/nvim/debugger.c b/src/nvim/debugger.c
index 8adeb19082..3e0cf82740 100644
--- a/src/nvim/debugger.c
+++ b/src/nvim/debugger.c
@@ -128,7 +128,7 @@ void do_debug(char *cmd)
       ignore_script = true;
     }
 
-    // don't debug any function call, e.g. from an expresion mapping
+    // don't debug any function call, e.g. from an expression mapping
     n = debug_break_level;
     debug_break_level = -1;
 
diff --git a/src/nvim/if_cscope.c b/src/nvim/if_cscope.c
index a23fa22da2..bc31d702f4 100644
--- a/src/nvim/if_cscope.c
+++ b/src/nvim/if_cscope.c
@@ -649,7 +649,7 @@ static char *cs_create_cmd(char *csoption, char *pattern)
     return NULL;
   }
 
-  // Skip white space before the patter, except for text and pattern search,
+  // Skip white space before the pattern, except for text and pattern search,
   // they may want to use the leading white space.
   pat = pattern;
   if (search != 4 && search != 6) {
diff --git a/src/nvim/keycodes.c b/src/nvim/keycodes.c
index 9ec37fd564..61dc2ac035 100644
--- a/src/nvim/keycodes.c
+++ b/src/nvim/keycodes.c
@@ -861,10 +861,9 @@ int get_mouse_button(int code, bool *is_click, bool *is_drag)
 /// @param[in]  from  What characters to replace.
 /// @param[in]  from_len  Length of the "from" argument.
 /// @param[out]  bufp  Location where results were saved in case of success (allocated).
-///                    if *bufp is non-NULL, it will be used directly. it is
-///                    assumed to be 128 bytes long (enough for transcoding LHS
-///                    of mapping)
-///                    Will be set to NULL in case of failure.
+///                    If `*bufp` is non-NULL, it will be used directly,
+///                    and is assumed to be 128 bytes long (enough for transcoding LHS of mapping),
+///                    and will be set to NULL in case of failure.
 /// @param[in]  flags  REPTERM_FROM_PART    see above
 ///                    REPTERM_DO_LT        also translate <lt>
 ///                    REPTERM_NO_SPECIAL   do not accept <key> notation
@@ -872,7 +871,7 @@ int get_mouse_button(int code, bool *is_click, bool *is_drag)
 /// @param[out]  did_simplify  set when some <C-H> code was simplied, unless it is NULL.
 /// @param[in]  cpo_flags  Relevant flags derived from p_cpo, see CPO_TO_CPO_FLAGS.
 ///
-/// @return  Pointer to an allocated memory, which is also saved to "bufp".
+/// @return  The same as what `*bufp` is set to.
 char *replace_termcodes(const char *const from, const size_t from_len, char **const bufp,
                         const int flags, bool *const did_simplify, const int cpo_flags)
   FUNC_ATTR_NONNULL_ARG(1, 3)
diff --git a/test/functional/vimscript/map_functions_spec.lua b/test/functional/vimscript/map_functions_spec.lua
index ed1863754a..8645b1e506 100644
--- a/test/functional/vimscript/map_functions_spec.lua
+++ b/test/functional/vimscript/map_functions_spec.lua
@@ -176,15 +176,12 @@ describe('mapset()', function()
 
   it('can restore mapping description from the dict returned by maparg()', function()
     meths.set_keymap('n', 'lhs', 'rhs', {desc = 'map description'})
-    eq('\nn  lhs           rhs\n                 map description',
-       helpers.exec_capture("nmap lhs"))
+    eq('\nn  lhs           rhs\n                 map description', exec_capture("nmap lhs"))
     local mapargs = funcs.maparg('lhs', 'n', false, true)
     meths.set_keymap('n', 'lhs', 'rhs', {desc = 'MAP DESCRIPTION'})
-    eq('\nn  lhs           rhs\n                 MAP DESCRIPTION',
-       helpers.exec_capture("nmap lhs"))
+    eq('\nn  lhs           rhs\n                 MAP DESCRIPTION', exec_capture("nmap lhs"))
     funcs.mapset('n', false, mapargs)
-    eq('\nn  lhs           rhs\n                 map description',
-       helpers.exec_capture("nmap lhs"))
+    eq('\nn  lhs           rhs\n                 map description', exec_capture("nmap lhs"))
   end)
 
   it('can restore "replace_keycodes" from the dict returned by maparg()', function()