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>

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
+    Tells Nvim the geometry of the popupmenu, to align floating windows with
-    external popup menu.
+    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: ~

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, 1)   [0, '', 0]
-		   	synconcealed(lnum, 2)   [1, 'X', 1]
+			synconcealed(lnum, 2)   [1, 'X', 1]
-		   	synconcealed(lnum, 3)   [1, 'X', 1]
+			synconcealed(lnum, 3)   [1, 'X', 1]
-		   	synconcealed(lnum, 4)   [1, 'X', 2]
+			synconcealed(lnum, 4)   [1, 'X', 2]
-		   	synconcealed(lnum, 5)   [1, 'X', 2]
+			synconcealed(lnum, 5)   [1, 'X', 2]
-		   	synconcealed(lnum, 6)   [0, '', 0]
+			synconcealed(lnum, 6)   [0, '', 0]
 
 
 synstack({lnum}, {col})					*synstack()*

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: >

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: >
+modified.  The value must have the same number of bytes in the range: >
-	:let blob[3:5] = [3, 4, 5]
+	: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

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 ...

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.
+Uppercase marks 'A to 'Z include the file name.  You can use them to jump from
-You can use them to jump from file to file.  You can only use an uppercase
+file to file.  You can only use an uppercase mark with an operator if the mark
-mark with an operator if the mark is in the current file.  The line number of
+is in the current file.  The line number of the mark remains correct, even if
-the mark remains correct, even if you insert/delete lines or edit another file
+you insert/delete lines or edit another file for a moment.  When the 'shada'
-for a moment.  When the 'shada' option is not empty, uppercase marks are
+option is not empty, uppercase marks are kept in the .shada file.  See
-kept in the .shada file.  See |shada-file-marks|.
+|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

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
+<	This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more
-	8th column thereafter.
+	for every column thereafter.
 
 	Note that the value of |'softtabstop'| will be ignored while
 	'varsofttabstop' is set.

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

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

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.
 

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

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: >

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.
 
 

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

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
+		Without {count}: Quit the current window.  If {count} is
-		given quit the {count} window
+		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|.
 

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()|,

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
 

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;
 

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) {

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
+///                    If `*bufp` is non-NULL, it will be used directly,
-///                    assumed to be 128 bytes long (enough for transcoding LHS
+///                    and is assumed to be 128 bytes long (enough for transcoding LHS of mapping),
-///                    of mapping)
+///                    and will be set to NULL in case of failure.
-///                    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)

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',
+    eq('\nn  lhs           rhs\n                 map description', exec_capture("nmap lhs"))
-       helpers.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',
+    eq('\nn  lhs           rhs\n                 MAP DESCRIPTION', exec_capture("nmap lhs"))
-       helpers.exec_capture("nmap lhs"))
     funcs.mapset('n', false, mapargs)
-    eq('\nn  lhs           rhs\n                 map description',
+    eq('\nn  lhs           rhs\n                 map description', exec_capture("nmap lhs"))
-       helpers.exec_capture("nmap lhs"))
   end)
 
   it('can restore "replace_keycodes" from the dict returned by maparg()', function()