vim-patch:partial:c58f91c: runtime(doc): Whitespace updates (#36160)

Use double sentence spacing and wrap lines at 'textwidth'.  Code
examples and tables were not wrapped unless this had already been done
locally.

closes: vim/vim#18453

https://github.com/vim/vim/commit/c58f91c035db09358c282f2a908e2aea4287785e

Fix incorrect docs in :h ModeChanged.
Cherry-pick :h bufnr() changes from patch 8.1.2080.

Co-authored-by: Doug Kearns <dougkearns@gmail.com>

1 files changed, 285 insertions, 271 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 2773d17546..99884aac99 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -92,7 +92,7 @@ function vim.fn.append(lnum, text) end
 
 --- Like |append()| but append the text in buffer {expr}.
 ---
---- This function works only for loaded buffers. First call
+--- This function works only for loaded buffers.  First call
 --- |bufload()| if needed.
 ---
 --- For the use of {buf}, see |bufname()|.
@@ -105,7 +105,7 @@ function vim.fn.append(lnum, text) end
 --- On success 0 is returned, on failure 1 is returned.
 ---
 --- If {buf} is not a valid buffer or {lnum} is not valid, an
---- error message is given. Example: >vim
+--- error message is given.  Example: >vim
 ---   let failed = appendbufline(13, 0, "# THE START")
 --- <However, when {text} is an empty list then no error is given
 --- for an invalid {lnum}, since {lnum} isn't actually used.
@@ -597,7 +597,11 @@ function vim.fn.bufname(buf) end
 --- above.
 --- If the buffer doesn't exist, -1 is returned.  Or, if the
 --- {create} argument is present and TRUE, a new, unlisted,
---- buffer is created and its number is returned.
+--- buffer is created and its number is returned.  Example: >vim
+---   let newbuf = bufnr('Scratch001', 1)
+--- <Using an empty name uses the current buffer.  To create a new
+--- buffer with an empty name use |bufadd()|.
+---
 --- bufnr("$") is the last buffer: >vim
 ---   let last_buffer = bufnr("$")
 --- <The result is a Number, which is the highest buffer number
@@ -848,7 +852,7 @@ function vim.fn.charcol(expr, winid) end
 --- index in the String {expr} instead of as the byte index.
 ---
 --- Returns -1 if the arguments are invalid or if there are less
---- than {idx} bytes. If there are exactly {idx} bytes the length
+--- than {idx} bytes.  If there are exactly {idx} bytes the length
 --- of the string in characters is returned.
 ---
 --- An error is given and -1 is returned if the first argument is
@@ -934,7 +938,7 @@ function vim.fn.clearmatches(win) end
 ---     completion began.
 ---    pum_visible  |TRUE| if popup menu is visible.
 ---     See |pumvisible()|.
----    matches  List of all completion candidates. Each item
+---    matches  List of all completion candidates.  Each item
 ---     is a string.
 ---    selected  Selected item index.  First index is zero.
 ---     Index is -1 if no item is selected (showing
@@ -955,7 +959,7 @@ function vim.fn.cmdcomplete_info() end
 --- When {expr} is "$", it means the end of the cursor line, so
 --- the result is the number of bytes in the cursor line plus one.
 --- Additionally {expr} can be [lnum, col]: a |List| with the line
---- and column number. Most useful when the column is "$", to get
+--- and column number.  Most useful when the column is "$", to get
 --- the last column of a specific line.  When "lnum" or "col" is
 --- out of range then col() returns zero.
 ---
@@ -992,10 +996,11 @@ function vim.fn.cmdcomplete_info() end
 --- @return integer
 function vim.fn.col(expr, winid) end
 
---- Set the matches for Insert mode completion.
---- Can only be used in Insert mode.  You need to use a mapping
---- with CTRL-R = (see |i_CTRL-R|).  It does not work after CTRL-O
---- or with an expression mapping.
+--- Set the matches for Insert mode completion.  Can only be used
+--- in Insert mode.  Typically invoked from a mapping with
+--- CTRL-R = (see |i_CTRL-R|), but may also be called from a
+--- |<Cmd>| mapping.  It does not work after CTRL-O or with an
+--- expression mapping.
 --- {startcol} is the byte offset in the line where the completed
 --- text start.  The text up to the cursor is the original text
 --- that will be replaced by the matches.  Use col('.') for an
@@ -1056,10 +1061,11 @@ function vim.fn.complete_check() end
 ---     See |pumvisible()|.
 ---    items  List of all completion candidates.  Each item
 ---     is a dictionary containing the entries "word",
----     "abbr", "menu", "kind", "info" and "user_data".
+---     "abbr", "menu", "kind", "info" and
+---     "user_data".
 ---     See |complete-items|.
 ---    matches  Same as "items", but only returns items that
----     are matching current query. If both "matches"
+---     are matching current query.  If both "matches"
 ---     and "items" are in "what", the returned list
 ---     will still be named "items", but each item
 ---     will have an additional "match" field.
@@ -1100,7 +1106,7 @@ function vim.fn.complete_check() end
 --- {what} are silently ignored.
 ---
 --- To get the position and size of the popup menu, see
---- |pum_getpos()|. It's also available in |v:event| during the
+--- |pum_getpos()|.  It's also available in |v:event| during the
 --- |CompleteChanged| event.
 ---
 --- Returns an empty |Dictionary| on error.
@@ -1119,13 +1125,13 @@ function vim.fn.complete_check() end
 function vim.fn.complete_info(what) end
 
 --- Searches backward from the given position and returns a List
---- of matches according to the 'isexpand' option. When no
+--- of matches according to the 'isexpand' option.  When no
 --- arguments are provided, uses the current cursor position.
 ---
 --- Each match is represented as a List containing
 --- [startcol, trigger_text] where:
 --- - startcol: column position where completion should start,
----   or -1 if no trigger position is found. For multi-character
+---   or -1 if no trigger position is found.  For multi-character
 ---   triggers, returns the column of the first character.
 --- - trigger_text: the matching trigger string from 'isexpand',
 ---   or empty string if no match was found or when using the
@@ -1273,7 +1279,7 @@ function vim.fn.cosh(expr) end
 --- When {ic} is given and it's |TRUE| then case is ignored.
 ---
 --- When {comp} is a string then the number of not overlapping
---- occurrences of {expr} is returned. Zero is returned when
+--- occurrences of {expr} is returned.  Zero is returned when
 --- {expr} is an empty string.
 ---
 --- @param comp string|table|any[]
@@ -1365,7 +1371,7 @@ function vim.fn.cursor(list) end
 
 --- Specifically used to interrupt a program being debugged.  It
 --- will cause process {pid} to get a SIGTRAP.  Behavior for other
---- processes is undefined. See |terminal-debug|.
+--- processes is undefined.  See |terminal-debug|.
 --- (Sends a SIGINT to a process {pid} other than MS-Windows)
 ---
 --- Returns |TRUE| if successfully interrupted the program.
@@ -1427,13 +1433,13 @@ function vim.fn.delete(fname, flags) end
 --- If {last} is omitted then delete line {first} only.
 --- On success 0 is returned, on failure 1 is returned.
 ---
---- This function works only for loaded buffers. First call
+--- This function works only for loaded buffers.  First call
 --- |bufload()| if needed.
 ---
 --- For the use of {buf}, see |bufname()| above.
 ---
---- {first} and {last} are used like with |getline()|. Note that
---- when using |line()| this refers to the current buffer. Use "$"
+--- {first} and {last} are used like with |getline()|.  Note that
+--- when using |line()| this refers to the current buffer.  Use "$"
 --- to refer to the last line in buffer {buf}.
 ---
 --- @param buf integer|string
@@ -1628,7 +1634,7 @@ function vim.fn.digraph_setlist(digraphlist) end
 --- @return integer
 function vim.fn.empty(expr) end
 
---- Return all of environment variables as dictionary. You can
+--- Return all of environment variables as dictionary.  You can
 --- check if an environment variable exists like this: >vim
 ---   echo has_key(environ(), 'HOME')
 --- <Note that the variable name may be CamelCase; to ignore case
@@ -2047,14 +2053,14 @@ function vim.fn.extendnew(expr1, expr2, expr3) end
 --- {string}.
 ---
 --- To include special keys into {string}, use double-quotes
---- and "\..." notation |expr-quote|. For example,
---- feedkeys("\<CR>") simulates pressing of the <Enter> key. But
+--- and "\..." notation |expr-quote|.  For example,
+--- feedkeys("\<CR>") simulates pressing of the <Enter> key.  But
 --- feedkeys('\<CR>') pushes 5 characters.
 --- The |<Ignore>| keycode may be used to exit the
 --- wait-for-character without doing anything.
 ---
 --- {mode} is a String, which can contain these character flags:
---- 'm'  Remap keys. This is default.  If {mode} is absent,
+--- 'm'  Remap keys.  This is default.  If {mode} is absent,
 ---   keys are remapped.
 --- 'n'  Do not remap keys.
 --- 't'  Handle keys as if typed; otherwise they are handled as
@@ -2073,7 +2079,7 @@ function vim.fn.extendnew(expr1, expr2, expr3) end
 ---   Note that if you manage to call feedkeys() while
 ---   executing commands, thus calling it recursively, then
 ---   all typeahead will be consumed by the last call.
---- '!'  When used with 'x' will not end Insert mode. Can be
+--- '!'  When used with 'x' will not end Insert mode.  Can be
 ---   used in a test when a timer is set to exit Insert mode
 ---   a little later.  Useful for testing CursorHoldI.
 ---
@@ -2091,7 +2097,7 @@ function vim.fn.feedkeys(string, mode) end
 --- @return any
 function vim.fn.file_readable(file) end
 
---- Copy the file pointed to by the name {from} to {to}. The
+--- Copy the file pointed to by the name {from} to {to}.  The
 --- result is a Number, which is |TRUE| if the file was copied
 --- successfully, and |FALSE| when it failed.
 --- If a file with name {to} already exists, it will fail.
@@ -2145,7 +2151,7 @@ function vim.fn.filewritable(file) end
 --- of the current item.  For a |Dictionary| |v:key| has the key
 --- of the current item and for a |List| |v:key| has the index of
 --- the current item.  For a |Blob| |v:key| has the index of the
---- current byte. For a |String| |v:key| has the index of the
+--- current byte.  For a |String| |v:key| has the index of the
 --- current character.
 --- Examples: >vim
 ---   call filter(mylist, 'v:val !~ "OLD"')
@@ -2182,8 +2188,8 @@ function vim.fn.filewritable(file) end
 --- or a new |Blob| or |String|.
 --- When an error is encountered while evaluating {expr2} no
 --- further items in {expr1} are processed.
---- When {expr2} is a Funcref errors inside a function are ignored,
---- unless it was defined with the "abort" flag.
+--- When {expr2} is a Funcref errors inside a function are
+--- ignored, unless it was defined with the "abort" flag.
 ---
 --- @param expr1 string|table
 --- @param expr2 string|function
@@ -2425,7 +2431,7 @@ function vim.fn.foldtext() end
 function vim.fn.foldtextresult(lnum) end
 
 --- {expr1} must be a |List|, |String|, |Blob| or |Dictionary|.
---- For each item in {expr1} execute {expr2}. {expr1} is not
+--- For each item in {expr1} execute {expr2}.  {expr1} is not
 --- modified; its values may be, as with |:lockvar| 1. |E741|
 --- See |map()| and |filter()| to modify {expr1}.
 ---
@@ -2435,7 +2441,7 @@ function vim.fn.foldtextresult(lnum) end
 --- of the current item.  For a |Dictionary| |v:key| has the key
 --- of the current item and for a |List| |v:key| has the index of
 --- the current item.  For a |Blob| |v:key| has the index of the
---- current byte. For a |String| |v:key| has the index of the
+--- current byte.  For a |String| |v:key| has the index of the
 --- current character.
 --- Examples: >vim
 ---   call foreach(mylist, 'let used[v:val] = v:true')
@@ -2455,8 +2461,8 @@ function vim.fn.foldtextresult(lnum) end
 --- Returns {expr1} in all cases.
 --- When an error is encountered while executing {expr2} no
 --- further items in {expr1} are processed.
---- When {expr2} is a Funcref errors inside a function are ignored,
---- unless it was defined with the "abort" flag.
+--- When {expr2} is a Funcref errors inside a function are
+--- ignored, unless it was defined with the "abort" flag.
 ---
 --- @param expr1 string|table
 --- @param expr2 string|function
@@ -2486,7 +2492,7 @@ function vim.fn.fullcommand(name) end
 --- It only works for an autoloaded function if it has already
 --- been loaded (to avoid mistakenly loading the autoload script
 --- when only intending to use the function name, use |function()|
---- instead). {name} cannot be a builtin function.
+--- instead).  {name} cannot be a builtin function.
 --- Returns 0 on error.
 ---
 --- @param name string
@@ -2501,7 +2507,7 @@ function vim.fn.funcref(name, arglist, dict) end
 ---
 --- {name} can also be a Funcref or a partial. When it is a
 --- partial the dict stored in it will be used and the {dict}
---- argument is not allowed. E.g.: >vim
+--- argument is not allowed.  E.g.: >vim
 ---   let FuncWithArg = function(dict.Func, [arg])
 ---   let Broken = function(dict.Func, [arg], dict)
 --- <
@@ -2510,8 +2516,8 @@ function vim.fn.funcref(name, arglist, dict) end
 --- same function.
 ---
 --- When {arglist} or {dict} is present this creates a partial.
---- That means the argument list and/or the dictionary is stored in
---- the Funcref and will be used when the Funcref is called.
+--- That means the argument list and/or the dictionary is stored
+--- in the Funcref and will be used when the Funcref is called.
 ---
 --- The arguments are passed to the function in front of other
 --- arguments, but after any argument from |method|.  Example: >vim
@@ -2548,7 +2554,7 @@ function vim.fn.funcref(name, arglist, dict) end
 ---   call Callback('one', 'two', 'name')
 ---
 --- <The Dictionary is only useful when calling a "dict" function.
---- In that case the {dict} is passed in as "self". Example: >vim
+--- In that case the {dict} is passed in as "self".  Example: >vim
 ---   function Callback() dict
 ---      echo "called for " .. self.name
 ---   endfunction
@@ -2813,8 +2819,8 @@ function vim.fn.getbufvar(buf, varname, def) end
 --- @return any
 function vim.fn.getcellwidths() end
 
---- Returns the |changelist| for the buffer {buf}. For the use
---- of {buf}, see |bufname()| above. If buffer {buf} doesn't
+--- Returns the |changelist| for the buffer {buf}.  For the use
+--- of {buf}, see |bufname()| above.  If buffer {buf} doesn't
 --- exist, an empty list is returned.
 ---
 --- The returned list contains two entries: a list with the change
@@ -2825,7 +2831,7 @@ function vim.fn.getcellwidths() end
 ---   coladd    column offset for 'virtualedit'
 ---   lnum    line number
 --- If buffer {buf} is the current buffer, then the current
---- position refers to the position in the list. For other
+--- position refers to the position in the list.  For other
 --- buffers, it is set to the length of the list.
 ---
 --- @param buf? integer|string
@@ -2947,7 +2953,7 @@ function vim.fn.getchar(expr, opts) end
 --- @return integer
 function vim.fn.getcharmod() end
 
---- Get the position for String {expr}. Same as |getpos()| but the
+--- Get the position for String {expr}.  Same as |getpos()| but the
 --- column number in the returned List is a character index
 --- instead of a byte index.
 --- If |getpos()| returns a very large column number, equal to
@@ -3064,7 +3070,7 @@ function vim.fn.getcmdprompt() end
 --- @return integer
 function vim.fn.getcmdscreenpos() end
 
---- Return the current command-line type. Possible return values
+--- Return the current command-line type.  Possible return values
 --- are:
 ---     :  normal Ex command
 ---     >  debug mode command |debug-mode|
@@ -3081,14 +3087,14 @@ function vim.fn.getcmdscreenpos() end
 --- @return ':'|'>'|'/'|'?'|'@'|'-'|'='|''
 function vim.fn.getcmdtype() end
 
---- Return the current |command-line-window| type. Possible return
---- values are the same as |getcmdtype()|. Returns an empty string
+--- Return the current |command-line-window| type.  Possible return
+--- values are the same as |getcmdtype()|.  Returns an empty string
 --- when not in the command-line window.
 ---
 --- @return ':'|'>'|'/'|'?'|'@'|'-'|'='|''
 function vim.fn.getcmdwintype() end
 
---- Return a list of command-line completion matches. The String
+--- Return a list of command-line completion matches.  The String
 --- {type} argument specifies what for.  The following completion
 --- types are supported:
 ---
@@ -3143,10 +3149,10 @@ function vim.fn.getcmdwintype() end
 ---
 --- If the optional {filtered} flag is set to 1, then 'wildignore'
 --- is applied to filter the results.  Otherwise all the matches
---- are returned. The 'wildignorecase' option always applies.
+--- are returned.  The 'wildignorecase' option always applies.
 ---
 --- If the 'wildoptions' option contains "fuzzy", then fuzzy
---- matching is used to get the completion matches. Otherwise
+--- matching is used to get the completion matches.  Otherwise
 --- regular expression matching is used.  Thus this function
 --- follows the user preference, what happens on the command line.
 --- If you do not want this you can make 'wildoptions' empty
@@ -3183,8 +3189,8 @@ function vim.fn.getcompletiontype(pat) end
 --- cursor vertically.  After |$| command it will be a very large
 --- number equal to |v:maxcol|.  Also see |getcursorcharpos()| and
 --- |getpos()|.
---- The first "bufnum" item is always zero. The byte position of
---- the cursor is returned in "col". To get the character
+--- The first "bufnum" item is always zero.  The byte position of
+--- the cursor is returned in "col".  To get the character
 --- position, use |getcursorcharpos()|.
 ---
 --- The optional {winid} argument can specify the window.  It can
@@ -3334,7 +3340,7 @@ function vim.fn.getftype(fname) end
 --- With {winnr} only use this window in the current tab page.
 --- {winnr} can also be a |window-ID|.
 --- With {winnr} and {tabnr} use the window in the specified tab
---- page.  If {winnr} or {tabnr} is invalid, an empty list is
+--- page.   If {winnr} or {tabnr} is invalid, an empty list is
 --- returned.
 ---
 --- The returned list contains two entries: a list with the jump
@@ -3392,19 +3398,19 @@ function vim.fn.getline(lnum, end_) end
 ---
 --- For a location list window, the displayed location list is
 --- returned.  For an invalid window number {nr}, an empty list is
---- returned. Otherwise, same as |getqflist()|.
+--- returned.  Otherwise, same as |getqflist()|.
 ---
 --- If the optional {what} dictionary argument is supplied, then
---- returns the items listed in {what} as a dictionary. Refer to
+--- returns the items listed in {what} as a dictionary.  Refer to
 --- |getqflist()| for the supported items in {what}.
 ---
 --- 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
----       from the location list. This field is
+---       from the location list.  This field is
 ---       applicable only when called from a
----       location list window. See
+---       location list window.  See
 ---       |location-list-file-window| for more
 ---       details.
 ---
@@ -3559,7 +3565,7 @@ function vim.fn.getpid() end
 ---
 --- For getting the cursor position see |getcurpos()|.
 --- The column number in the returned List is the byte position
---- within the line. To get the character position in the line,
+--- within the line.  To get the character position in the line,
 --- use |getcharpos()|.
 ---
 --- Note that for '< and '> Visual mode matters: when it is "V"
@@ -3602,7 +3608,7 @@ function vim.fn.getpos(expr) end
 ---     any type.
 ---
 --- When there is no error list or it's empty, an empty list is
---- returned. Quickfix list entries with a non-existing buffer
+--- returned.  Quickfix list entries with a non-existing buffer
 --- number are returned with "bufnr" set to zero (Note: some
 --- functions accept buffer number zero for the alternate buffer,
 --- you may need to explicitly check for zero).
@@ -3615,12 +3621,12 @@ function vim.fn.getpos(expr) end
 ---   endfor
 --- <
 --- If the optional {what} dictionary argument is supplied, then
---- returns only the items listed in {what} as a dictionary. The
+--- returns only the items listed in {what} as a dictionary.  The
 --- following string items are supported in {what}:
 ---   changedtick  get the total number of changes made
 ---       to the list |quickfix-changedtick|
 ---   context  get the |quickfix-context|
----   efm  errorformat to use when parsing "lines". If
+---   efm  errorformat to use when parsing "lines".  If
 ---     not present, then the 'errorformat' option
 ---     value is used.
 ---   id  get information for the quickfix list with
@@ -3634,24 +3640,24 @@ function vim.fn.getpos(expr) end
 ---   lines  parse a list of lines using 'efm' and return
 ---     the resulting entries.  Only a |List| type is
 ---     accepted.  The current quickfix list is not
----     modified. See |quickfix-parse|.
+---     modified.  See |quickfix-parse|.
 ---   nr  get information for this quickfix list; zero
 ---     means the current quickfix list and "$" means
 ---     the last quickfix list
 ---   qfbufnr number of the buffer displayed in the quickfix
----     window. Returns 0 if the quickfix buffer is
----     not present. See |quickfix-buffer|.
+---     window.  Returns 0 if the quickfix buffer is
+---     not present.  See |quickfix-buffer|.
 ---   size  number of entries in the quickfix list
 ---   title  get the list title |quickfix-title|
 ---   winid  get the quickfix |window-ID|
 ---   all  all of the above quickfix properties
---- Non-string items in {what} are ignored. To get the value of a
+--- Non-string items in {what} are ignored.  To get the value of a
 --- particular item, set it to zero.
 --- If "nr" is not present then the current quickfix list is used.
 --- If both "nr" and a non-zero "id" are specified, then the list
 --- specified by "id" is used.
 --- To get the number of lists in the quickfix stack, set "nr" to
---- "$" in {what}. The "nr" value in the returned dictionary
+--- "$" in {what}.  The "nr" value in the returned dictionary
 --- contains the quickfix stack size.
 --- When "lines" is specified, all the other items except "efm"
 --- are ignored.  The returned dictionary contains the entry
@@ -3660,22 +3666,23 @@ function vim.fn.getpos(expr) end
 --- The returned dictionary contains the following entries:
 ---   changedtick  total number of changes made to the
 ---       list |quickfix-changedtick|
----   context  quickfix list context. See |quickfix-context|
+---   context  quickfix list context.  See |quickfix-context|
 ---     If not present, set to "".
----   id  quickfix list ID |quickfix-ID|. If not
----     present, set to 0.
----   idx  index of the quickfix entry in the list. If not
+---   id  quickfix list ID |quickfix-ID|.  If not
 ---     present, set to 0.
----   items  quickfix list entries. If not present, set to
+---   idx  index of the quickfix entry in the list.  If
+---     not present, set to 0.
+---   items  quickfix list entries.  If not present, set to
 ---     an empty list.
----   nr  quickfix list number. If not present, set to 0
+---   nr  quickfix list number.  If not present, set to
+---     0
 ---   qfbufnr  number of the buffer displayed in the quickfix
----     window. If not present, set to 0.
----   size  number of entries in the quickfix list. If not
----     present, set to 0.
----   title  quickfix list title text. If not present, set
+---     window.  If not present, set to 0.
+---   size  number of entries in the quickfix list.  If
+---     not present, set to 0.
+---   title  quickfix list title text.  If not present, set
 ---     to "".
----   winid  quickfix |window-ID|. If not present, set to 0
+---   winid  quickfix |window-ID|.  If not present, set to 0
 ---
 --- Examples (See also |getqflist-examples|): >vim
 ---   echo getqflist({'all': 1})
@@ -3701,7 +3708,7 @@ function vim.fn.getqflist(what) end
 --- argument is ignored, thus you can always give it.
 ---
 --- If {list} is present and |TRUE|, the result type is changed
---- to |List|. Each list item is one text line. Use it if you care
+--- to |List|.  Each list item is one text line.  Use it if you care
 --- about zero bytes possibly present inside register: without
 --- third argument both NLs and zero bytes are represented as NLs
 --- (see |NL-used-for-Nul|).
@@ -3865,7 +3872,7 @@ function vim.fn.getregtype(regname) end
 ---
 --- The optional Dict argument {opts} supports the following
 --- optional items:
----     name  Script name match pattern. If specified,
+---     name  Script name match pattern.  If specified,
 ---     and "sid" is not specified, information about
 ---     scripts with a name that match the pattern
 ---     "name" are returned.
@@ -3914,7 +3921,7 @@ function vim.fn.getscriptinfo(opts) end
 function vim.fn.getstacktrace() end
 
 --- If {tabnr} is not specified, then information about all the
---- tab pages is returned as a |List|. Each List item is a
+--- tab pages is returned as a |List|.  Each List item is a
 --- |Dictionary|.  Otherwise, {tabnr} specifies the tab page
 --- number and information about that one is returned.  If the tab
 --- page does not exist an empty List is returned.
@@ -3983,10 +3990,10 @@ function vim.fn.gettabwinvar(tabnr, winnr, varname, def) end
 --- When window {winnr} doesn't exist, an empty Dict is returned.
 ---
 --- The returned dictionary contains the following entries:
----   curidx    Current index in the stack. When at
+---   curidx    Current index in the stack.  When at
 ---       top of the stack, set to (length + 1).
 ---       Index of bottom of the stack is 1.
----   items    List of items in the stack. Each item
+---   items    List of items in the stack.  Each item
 ---       is a dictionary containing the
 ---       entries described below.
 ---   length    Number of entries in the stack.
@@ -3997,9 +4004,9 @@ function vim.fn.gettabwinvar(tabnr, winnr, varname, def) end
 ---   from    cursor position before the tag jump.
 ---       See |getpos()| for the format of the
 ---       returned list.
----   matchnr    current matching tag number. Used when
----       multiple matching tags are found for a
----       name.
+---   matchnr    current matching tag number.  Used
+---       when multiple matching tags are found
+---       for a name.
 ---   tagname    name of the tag
 ---
 --- See |tagstack| for more information about the tag stack.
@@ -4123,7 +4130,7 @@ function vim.fn.getwinvar(winnr, varname, def) end
 --- 'wildignorecase' always applies.
 ---
 --- When {list} is present and it is |TRUE| the result is a |List|
---- with all matching files. The advantage of using a List is,
+--- with all matching files.  The advantage of using a List is,
 --- you also get filenames containing newlines correctly.
 --- Otherwise the result is a String and when there are several
 --- matches, they are separated by <NL> characters.
@@ -4193,10 +4200,10 @@ function vim.fn.glob2regpat(string) end
 --- 'suffixes' affect the ordering of matches.
 ---
 --- When {list} is present and it is |TRUE| the result is a |List|
---- with all matching files. The advantage of using a List is, you
---- also get filenames containing newlines correctly. Otherwise
---- the result is a String and when there are several matches,
---- they are separated by <NL> characters.  Example: >vim
+--- with all matching files.  The advantage of using a List is,
+--- you also get filenames containing newlines correctly.
+--- Otherwise the result is a String and when there are several
+--- matches, they are separated by <NL> characters.  Example: >vim
 ---   echo globpath(&rtp, "syntax/c.vim", 0, 1)
 --- <
 --- {allinks} is used as with |glob()|.
@@ -4771,7 +4778,8 @@ function vim.fn.inputlist(textlist) end
 --- Restore typeahead that was saved with a previous |inputsave()|.
 --- Should be called the same number of times inputsave() is
 --- called.  Calling it more often is harmless though.
---- Returns TRUE when there is nothing to restore, FALSE otherwise.
+--- Returns TRUE when there is nothing to restore, FALSE
+--- otherwise.
 ---
 --- @return integer
 function vim.fn.inputrestore() end
@@ -4850,10 +4858,11 @@ function vim.fn.invert(expr) end
 
 --- The result is a Number, which is |TRUE| when {path} is an
 --- absolute path.
---- On Unix, a path is considered absolute when it starts with '/'.
---- On MS-Windows, it is considered absolute when it starts with an
---- optional drive prefix and is followed by a '\' or '/'. UNC paths
---- are always absolute.
+--- On Unix, a path is considered absolute when it starts with
+--- '/'.
+--- On MS-Windows, it is considered absolute when it starts with
+--- an optional drive prefix and is followed by a '\' or '/'.  UNC
+--- paths are always absolute.
 --- Example: >vim
 ---   echo isabsolutepath('/usr/share/')  " 1
 ---   echo isabsolutepath('./foobar')    " 0
@@ -5376,7 +5385,7 @@ function vim.fn.log10(expr) end
 --- of the current item.  For a |Dictionary| |v:key| has the key
 --- of the current item and for a |List| |v:key| has the index of
 --- the current item.  For a |Blob| |v:key| has the index of the
---- current byte. For a |String| |v:key| has the index of the
+--- current byte.  For a |String| |v:key| has the index of the
 --- current character.
 --- Example: >vim
 ---   call map(mylist, '"> " .. v:val .. " <"')
@@ -5390,7 +5399,7 @@ function vim.fn.log10(expr) end
 --- If {expr2} is a |Funcref| it is called with two arguments:
 ---   1. The key or the index of the current item.
 ---   2. the value of the current item.
---- The function must return the new value of the item. Example
+--- The function must return the new value of the item.  Example
 --- that changes each value by "key-value": >vim
 ---   func KeyValue(key, val)
 ---     return a:key .. '-' .. a:val
@@ -5411,8 +5420,8 @@ function vim.fn.log10(expr) end
 --- or a new |Blob| or |String|.
 --- When an error is encountered while evaluating {expr2} no
 --- further items in {expr1} are processed.
---- When {expr2} is a Funcref errors inside a function are ignored,
---- unless it was defined with the "abort" flag.
+--- When {expr2} is a Funcref errors inside a function are
+--- ignored, unless it was defined with the "abort" flag.
 ---
 --- @param expr1 string|table|any[]
 --- @param expr2 string|function
@@ -5422,8 +5431,8 @@ function vim.fn.map(expr1, expr2) end
 --- When {dict} is omitted or zero: Return the rhs of mapping
 --- {name} in mode {mode}.  The returned String has special
 --- characters translated like in the output of the ":map" command
---- listing. When {dict} is TRUE a dictionary is returned, see
---- below. To get a list of all mappings see |maplist()|.
+--- listing.  When {dict} is TRUE a dictionary is returned, see
+--- below.  To get a list of all mappings see |maplist()|.
 ---
 --- When there is no mapping for {name}, an empty String is
 --- returned if {dict} is FALSE, otherwise returns an empty Dict.
@@ -5462,7 +5471,7 @@ function vim.fn.map(expr1, expr2) end
 ---   "script"   1 if mapping was defined with <script>.
 ---   "expr"     1 for an expression mapping (|:map-<expr>|).
 ---   "buffer"   1 for a buffer local mapping (|:map-local|).
----   "mode"     Modes for which the mapping is defined. In
+---   "mode"     Modes for which the mapping is defined.  In
 ---        addition to the modes mentioned above, these
 ---        characters will be used:
 ---        " "     Normal, Visual and Operator-pending
@@ -5477,7 +5486,7 @@ function vim.fn.map(expr1, expr2) end
 ---   "abbr"     True if this is an |abbreviation|.
 ---   "mode_bits" Nvim's internal binary representation of "mode".
 ---        |mapset()| ignores this; only "mode" is used.
----        See |maplist()| for usage examples. The values
+---        See |maplist()| for usage examples.  The values
 ---        are from src/nvim/state_defs.h and may change in
 ---        the future.
 ---
@@ -5553,9 +5562,9 @@ function vim.fn.mapcheck(name, mode, abbr) end
 ---     \ match(get(m, 'rhs', ''), 'MultiMatch') >= 0
 ---     \ })
 --- <It can be tricky to find mappings for particular |:map-modes|.
---- |mapping-dict|'s "mode_bits" can simplify this. For example,
+--- |mapping-dict|'s "mode_bits" can simplify this.  For example,
 --- the mode_bits for Normal, Insert or Command-line modes are
---- 0x19. To find all the mappings available in those modes you
+--- 0x19.  To find all the mappings available in those modes you
 --- can do: >vim
 ---   let saved_maps = []
 ---   for m in maplist()
@@ -5566,7 +5575,7 @@ function vim.fn.mapcheck(name, mode, abbr) end
 ---   echo saved_maps->mapnew({_, m -> m.lhs})
 --- <The values of the mode_bits are defined in Nvim's
 --- src/nvim/state_defs.h file and they can be discovered at
---- runtime using |:map-commands| and "maplist()". Example: >vim
+--- runtime using |:map-commands| and "maplist()".  Example: >vim
 ---   omap xyzzy <Nop>
 ---   let op_bit = maplist()->filter(
 ---       \ {_, m -> m.lhs == 'xyzzy'})[0].mode_bits
@@ -5597,8 +5606,9 @@ function vim.fn.mapset(mode, abbr, dict) end
 --- Restore a mapping from a dictionary, possibly returned by
 --- |maparg()| or |maplist()|.  A buffer mapping, when dict.buffer
 --- is true, is set on the current buffer; it is up to the caller
---- to ensure that the intended buffer is the current buffer. This
---- feature allows copying mappings from one buffer to another.
+--- to ensure that the intended buffer is the current buffer.
+--- This feature allows copying mappings from one buffer to
+--- another.
 --- The dict.mode value may restore a single mapping that covers
 --- more than one mode, like with mode values of '!', ' ', "nox",
 --- or 'v'. *E1276*
@@ -5735,9 +5745,9 @@ function vim.fn.match(expr, pat, start, count) end
 --- automatically chooses a free ID, which is at least 1000.
 ---
 --- The optional {dict} argument allows for further custom
---- values. Currently this is used to specify a match specific
+--- values.  Currently this is used to specify a match specific
 --- conceal character that will be shown for |hl-Conceal|
---- highlighted matches. The dict can have the following members:
+--- highlighted matches.  The dict can have the following members:
 ---
 ---   conceal      Special character to show instead of the
 ---         match (only for |hl-Conceal| highlighted
@@ -5769,9 +5779,9 @@ function vim.fn.match(expr, pat, start, count) end
 function vim.fn.matchadd(group, pattern, priority, id, dict) end
 
 --- Same as |matchadd()|, but requires a list of positions {pos}
---- instead of a pattern. This command is faster than |matchadd()|
+--- instead of a pattern.  This command is faster than |matchadd()|
 --- because it does not handle regular expressions and it sets
---- buffer line boundaries to redraw screen. It is supposed to be
+--- buffer line boundaries to redraw screen.  It is supposed to be
 --- used when fast match additions and deletions are required, for
 --- example to highlight matching parentheses.
 ---           *E5030* *E5031*
@@ -5779,14 +5789,14 @@ function vim.fn.matchadd(group, pattern, priority, id, dict) end
 --- these:
 --- - A number.  This whole line will be highlighted.  The first
 ---   line has number 1.
---- - A list with one number, e.g., [23]. The whole line with this
----   number will be highlighted.
---- - A list with two numbers, e.g., [23, 11]. The first number is
----   the line number, the second one is the column number (first
----   column is 1, the value must correspond to the byte index as
----   |col()| would return).  The character at this position will
----   be highlighted.
---- - A list with three numbers, e.g., [23, 11, 3]. As above, but
+--- - A list with one number, e.g., [23].  The whole line with
+---   this number will be highlighted.
+--- - A list with two numbers, e.g., [23, 11].  The first number
+---   is the line number, the second one is the column number
+---   (first column is 1, the value must correspond to the byte
+---   index as |col()| would return).  The character at this
+---   position will be highlighted.
+--- - A list with three numbers, e.g., [23, 11, 3].  As above, but
 ---   the third number gives the length of the highlight in bytes.
 ---
 --- Entries with zero and negative line numbers are silently
@@ -5821,7 +5831,7 @@ function vim.fn.matchaddpos(group, pos, priority, id, dict) end
 --- When there is no match item set returns ['', ''].
 --- This is useful to save and restore a |:match|.
 --- Highlighting matches using the |:match| commands are limited
---- to three matches. |matchadd()| does not have this limitation.
+--- to three matches.  |matchadd()| does not have this limitation.
 ---
 --- @param nr integer
 --- @return string[]
@@ -5842,7 +5852,7 @@ function vim.fn.matcharg(nr) end
 ---     text  matched string
 --- Note that there can be multiple matches in a single line.
 ---
---- This function works only for loaded buffers. First call
+--- This function works only for loaded buffers.  First call
 --- |bufload()| if needed.
 ---
 --- See |match-pattern| for information about the effect of some
@@ -5916,7 +5926,7 @@ function vim.fn.matchdelete(id, win) end
 function vim.fn.matchend(expr, pat, start, count) end
 
 --- If {list} is a list of strings, then returns a |List| with all
---- the strings in {list} that fuzzy match {str}. The strings in
+--- the strings in {list} that fuzzy match {str}.  The strings in
 --- the returned list are sorted based on the matching score.
 ---
 --- The optional {dict} argument always supports the following
@@ -5930,7 +5940,7 @@ function vim.fn.matchend(expr, pat, start, count) end
 --- If {list} is a list of dictionaries, then the optional {dict}
 --- argument supports the following additional items:
 ---     key    Key of the item which is fuzzy matched against
----     {str}. The value of this item should be a
+---     {str}.  The value of this item should be a
 ---     string.
 ---     text_cb  |Funcref| that will be called for every item
 ---     in {list} to get the text for fuzzy matching.
@@ -5946,7 +5956,7 @@ function vim.fn.matchend(expr, pat, start, count) end
 --- then the list of strings that have all the words is returned.
 ---
 --- If there are no matching strings or there is an error, then an
---- empty list is returned. If length of {str} is greater than
+--- empty list is returned.  If length of {str} is greater than
 --- 256, then returns an empty list.
 ---
 --- When {limit} is given, matchfuzzy() will find up to this
@@ -6109,7 +6119,7 @@ function vim.fn.matchstrlist(list, pat, dict) end
 --- @return table
 function vim.fn.matchstrpos(expr, pat, start, count) end
 
---- Return the maximum value of all items in {expr}. Example: >vim
+--- Return the maximum value of all items in {expr}.  Example: >vim
 ---   echo max([apples, pears, oranges])
 ---
 --- <{expr} can be a |List| or a