doc + extmarks tweaks #11421

- nvim_buf_get_extmarks: rename "amount" => "limit"
- rename `set_extmark_index_from_obj`

runtime/doc/api.txt

@@ -19,6 +19,7 @@ API Usage						*api-rpc* *RPC* *rpc*
 							*msgpack-rpc*
 RPC is the typical way to control Nvim programmatically.  Nvim implements the
 MessagePack-RPC protocol:
+  https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
   https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
 
 Many clients use the API: user interfaces (GUIs), remote plugins, scripts like
@@ -935,8 +936,8 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                                   'list' options. 'signcolumn' is changed to
                                   `auto` and 'colorcolumn' is cleared. The
                                   end-of-buffer region is hidden by setting
-                                  `eob` flag of 'fillchars' to a space char, and
+                                  `eob` flag of 'fillchars' to a space char,
-                                  clearing the |EndOfBuffer| region in
+                                  and clearing the |EndOfBuffer| region in
                                   'winhighlight'.
 
                 Return: ~
@@ -1022,7 +1023,7 @@ nvim_put({lines}, {type}, {after}, {follow})                      *nvim_put()*
                     {type}    Edit behavior: any |getregtype()| result, or:
                               • "b" |blockwise-visual| mode (may include
                                 width, e.g. "b3")
-                              • "c" |characterwise| mode
+                              • "c" |charwise| mode
                               • "l" |linewise| mode
                               • "" guess by contents, see |setreg()|
                     {after}   Insert after cursor (like |p|), or before (like
@@ -1797,81 +1798,93 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id})
                 Returns position for a given extmark id
 
                 Parameters: ~
-                    {buffer}     The buffer handle
+                    {buffer}  Buffer handle, or 0 for current buffer
-                    {namespace}  a identifier returned previously with
+                    {ns_id}   Namespace id from |nvim_create_namespace()|
-                                 nvim_create_namespace
+                    {id}      Extmark id
-                    {id}         the extmark id
 
                 Return: ~
                     (row, col) tuple or empty list () if extmark id was absent
 
                                                      *nvim_buf_get_extmarks()*
 nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
-                List extmarks in a range (inclusive)
+                Gets extmarks in "traversal order" from a |charwise| region
+                defined by buffer positions (inclusive, 0-indexed
+                |api-indexing|).
 
-                range ends can be specified as (row, col) tuples, as well as
+                Region can be given as (row,col) tuples, or valid extmark ids
-                extmark ids in the same namespace. In addition, 0 and -1 works
+                (whose positions define the bounds). 0 and -1 are understood
-                as shorthands for (0,0) and (-1,-1) respectively, so that all
+                as (0,0) and (-1,-1) respectively, thus the following are
-                marks in the buffer can be queried as:
+                equivalent:
+>
+                  nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
+                  nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
+<
 
-                all_marks = nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
+                If `end` is less than `start` , traversal works backwards.
+                (Useful with `limit` , to get the first marks prior to a given
+                position.)
 
-                If end is a lower position than start, then the range will be
+                Example:
-                traversed backwards. This is mostly useful with limited
+>
-                amount, to be able to get the first marks prior to a given
+                  local a   = vim.api
-                position.
+                  local pos = a.nvim_win_get_cursor(0)
+                  local ns  = a.nvim_create_namespace('my-plugin')
+                  -- Create new extmark at line 1, column 1.
+                  local m1  = a.nvim_buf_set_extmark(0, ns, 0, 0, 0, {})
+                  -- Create new extmark at line 3, column 1.
+                  local m2  = a.nvim_buf_set_extmark(0, ns, 0, 2, 0, {})
+                  -- Get extmarks only from line 3.
+                  local ms  = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
+                  -- Get all marks in this buffer + namespace.
+                  local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
+                  print(vim.inspect(ms))
+<
 
                 Parameters: ~
-                    {buffer}  The buffer handle
+                    {buffer}  Buffer handle, or 0 for current buffer
-                    {ns_id}   An id returned previously from
+                    {ns_id}   Namespace id from |nvim_create_namespace()|
-                              nvim_create_namespace
+                    {start}   Start of range, given as (row, col) or valid
-                    {start}   One of: extmark id, (row, col) or 0, -1 for
+                              extmark id (whose position defines the bound)
-                              buffer ends
+                    {end}     End of range, given as (row, col) or valid
-                    {end}     One of: extmark id, (row, col) or 0, -1 for
+                              extmark id (whose position defines the bound)
-                              buffer ends
+                    {opts}    Optional parameters. Keys:
-                    {opts}    additional options. Supports the keys:
+                              • limit: Maximum number of marks to return
-                              • amount: Maximum number of marks to return
 
                 Return: ~
-                    [[extmark_id, row, col], ...]
+                    List of [extmark_id, row, col] tuples in "traversal
+                    order".
 
                                                       *nvim_buf_set_extmark()*
 nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts})
-                Create or update an extmark at a position
+                Creates or updates an extmark.
 
-                If an invalid namespace is given, an error will be raised.
+                To create a new extmark, pass id=0. The extmark id will be
-
+                returned. It is also allowed to create a new mark by passing
-                To create a new extmark, pass in id=0. The new extmark id will
+                in a previously unused id, but the caller must then keep track
-                be returned. To move an existing mark, pass in its id.
+                of existing and unused ids itself. (Useful over RPC, to avoid
-
+                waiting for the return value.)
-                It is also allowed to create a new mark by passing in a
-                previously unused id, but the caller must then keep track of
-                existing and unused ids itself. This is mainly useful over
-                RPC, to avoid needing to wait for the return value.
 
                 Parameters: ~
-                    {buffer}  The buffer handle
+                    {buffer}  Buffer handle, or 0 for current buffer
-                    {ns_id}   a identifier returned previously with
+                    {ns_id}   Namespace id from |nvim_create_namespace()|
-                              nvim_create_namespace
+                    {id}      Extmark id, or 0 to create new
-                    {id}      The extmark's id or 0 to create a new mark.
+                    {line}    Line number where to place the mark
-                    {line}    The row to set the extmark to.
+                    {col}     Column where to place the mark
-                    {col}     The column to set the extmark to.
                     {opts}    Optional parameters. Currently not used.
 
                 Return: ~
-                    the id of the extmark.
+                    Id of the created/updated extmark
 
 nvim_buf_del_extmark({buffer}, {ns_id}, {id})         *nvim_buf_del_extmark()*
-                Remove an extmark
+                Removes an extmark.
 
                 Parameters: ~
-                    {buffer}  The buffer handle
+                    {buffer}  Buffer handle, or 0 for current buffer
-                    {ns_id}   a identifier returned previously with
+                    {ns_id}   Namespace id from |nvim_create_namespace()|
-                              nvim_create_namespace
+                    {id}      Extmark id
-                    {id}      The extmarks's id
 
                 Return: ~
-                    true on success, false if the extmark was not found.
+                    true if the extmark was found, else false
 
                                                     *nvim_buf_add_highlight()*
 nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
@@ -1916,8 +1929,8 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
 
                                                   *nvim_buf_clear_namespace()*
 nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
-                Clears namespaced objects, highlights and virtual text, from a
+                Clears namespaced objects (highlights, extmarks, virtual text)
-                line range
+                from a region.
 
                 Lines are 0-indexed. |api-indexing| To clear the namespace in
                 the entire buffer, specify line_start=0 and line_end=-1.

runtime/doc/change.txt

@@ -90,7 +90,7 @@ start and end of the motion are not in the same line, and there are only
 blanks before the start and there are no non-blanks after the end of the
 motion, the delete becomes linewise.  This means that the delete also removes
 the line of blanks that you might expect to remain. Use the |o_v| operator to
-force the motion to be characterwise.
+force the motion to be charwise.
 
 Trying to delete an empty region of text (e.g., "d0" in the first column)
 is an error when 'cpoptions' includes the 'E' flag.
@@ -1074,7 +1074,7 @@ also use these commands to move text from one file to another, because Vim
 preserves all registers when changing buffers (the CTRL-^ command is a quick
 way to toggle between two files).
 
-				*linewise-register* *characterwise-register*
+				*linewise-register* *charwise-register*
 You can repeat the put commands with "." (except for :put) and undo them.  If
 the command that was used to get the text into the register was |linewise|,
 Vim inserts the text below ("p") or above ("P") the line where the cursor is.
@@ -1116,10 +1116,9 @@ this happen.  However, if the width of the block is not a multiple of a <Tab>
 width and the text after the inserted block contains <Tab>s, that text may be
 misaligned.
 
-Note that after a characterwise yank command, Vim leaves the cursor on the
+Note that after a charwise yank command, Vim leaves the cursor on the first
-first yanked character that is closest to the start of the buffer.  This means
+yanked character that is closest to the start of the buffer.  This means that
-that "yl" doesn't move the cursor, but "yh" moves the cursor one character
+"yl" doesn't move the cursor, but "yh" moves the cursor one character left.
-left.
 Rationale:	In Vi the "y" command followed by a backwards motion would
 		sometimes not move the cursor to the first yanked character,
 		because redisplaying was skipped.  In Vim it always moves to

runtime/doc/eval.txt

@@ -4727,7 +4727,7 @@ getreg([{regname} [, 1 [, {list}]]])			*getreg()*
 getregtype([{regname}])					*getregtype()*
 		The result is a String, which is type of register {regname}.
 		The value will be one of:
-		    "v"			for |characterwise| text
+		    "v"			for |charwise| text
 		    "V"			for |linewise| text
 		    "<CTRL-V>{width}"	for |blockwise-visual| text
 		    ""			for an empty or unknown register
@@ -6131,7 +6131,7 @@ mode([expr])	Return a string that indicates the current mode.
 
 		   n	    Normal
 		   no	    Operator-pending
-		   nov	    Operator-pending (forced characterwise |o_v|)
+		   nov	    Operator-pending (forced charwise |o_v|)
 		   noV	    Operator-pending (forced linewise |o_V|)
 		   noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|)
 		   niI	    Normal using |i_CTRL-O| in |Insert-mode|
@@ -7441,7 +7441,7 @@ setreg({regname}, {value} [, {options}])
 		If {options} contains "a" or {regname} is upper case,
 		then the value is appended.
 		{options} can also contain a register type specification:
-		    "c" or "v"	      |characterwise| mode
+		    "c" or "v"	      |charwise| mode
 		    "l" or "V"	      |linewise| mode
 		    "b" or "<CTRL-V>" |blockwise-visual| mode
 		If a number immediately follows "b" or "<CTRL-V>" then this is
@@ -9708,7 +9708,7 @@ This does NOT work: >
 			register, "@/" for the search pattern.
 			If the result of {expr1} ends in a <CR> or <NL>, the
 			register will be linewise, otherwise it will be set to
-			characterwise.
+			charwise.
 			This can be used to clear the last search pattern: >
 				:let @/ = ""
 <			This is different from searching for an empty string,

runtime/doc/index.txt

@@ -404,7 +404,7 @@ tag		char	      note action in Normal mode	~
 |t|		t{char}		1  cursor till before Nth occurrence of {char}
 				   to the right
 |u|		u		2  undo changes
-|v|		v		   start characterwise Visual mode
+|v|		v		   start charwise Visual mode
 |w|		w		1  cursor N words forward
 |x|		["x]x		2  delete N characters under and after the
 				   cursor [into register x]
@@ -866,7 +866,7 @@ These can be used after an operator, but before a {motion} has been entered.
 
 tag		char		action in Operator-pending mode	~
 -----------------------------------------------------------------------
-|o_v|		v		force operator to work characterwise
+|o_v|		v		force operator to work charwise
 |o_V|		V		force operator to work linewise
 |o_CTRL-V|	CTRL-V		force operator to work blockwise
 
@@ -978,7 +978,7 @@ tag		command	      note action in Visual mode	~
 |v_r|		r		2  replace highlighted area with a character
 |v_s|		s		2  delete highlighted area and start insert
 |v_u|		u		2  make highlighted area lowercase
-|v_v|		v		   make Visual mode characterwise or stop
+|v_v|		v		   make Visual mode charwise or stop
 				   Visual mode
 |v_x|		x		2  delete the highlighted area
 |v_y|		y		   yank the highlighted area

runtime/doc/intro.txt

@@ -271,7 +271,7 @@ and <> are part of what you type, the context should make this clear.
 		  operator is pending.
 		- Ex commands can be used to move the cursor.  This can be
 		  used to call a function that does some complicated motion.
-		  The motion is always characterwise exclusive, no matter
+		  The motion is always charwise exclusive, no matter
 		  what ":" command is used.  This means it's impossible to
 		  include the last character of a line without the line break
 		  (unless 'virtualedit' is set).

runtime/doc/lsp.txt

@@ -1,18 +1,18 @@
-*lsp.txt* The Language Server Protocol
+*lsp.txt*   Nvim LSP API
 
-        NVIM REFERENCE MANUAL
+                            NVIM REFERENCE MANUAL
 
 
-Neovim Language Server Protocol (LSP) API
+Nvim Language Server Protocol (LSP) API                                *lsp*
 
-Neovim exposes a powerful API that conforms to Microsoft's published Language
+Nvim is a client to the Language Server Protocol:
-Server Protocol specification. The documentation can be found here:
 
   https://microsoft.github.io/language-server-protocol/
 
+                                      Type |gO| to see the table of contents.
 
 ================================================================================
-                                                                       *lsp-api*
+LSP API                                                                *lsp-api*
 
 Neovim exposes a API for the language server protocol. To get the real benefits
 of this API, a language server must be installed.
@@ -261,13 +261,16 @@ vim.lsp.rpc_response_error({code}, [{message}], [{data}])
   the server.
 
 ================================================================================
-                                                     *vim.lsp.default_callbacks*
+LSP CALLBACKS                                           *lsp-callbacks*
 
-The |vim.lsp.default_callbacks| table contains the default |lsp-callbacks|
+DEFAULT CALLBACKS ~
-that are used when creating a new client. The keys are the LSP method names.
+                                                   *vim.lsp.default_callbacks*
+The `vim.lsp.default_callbacks` table defines default callbacks used when
+creating a new client. Keys are LSP method names: >
 
-The following requests and notifications have built-in callbacks defined to
+  :lua print(vim.inspect(vim.tbl_keys(vim.lsp.default_callbacks)))
-handle the response in an idiomatic way.
+
+These LSP requests/notifications are defined by default:
 
   textDocument/publishDiagnostics
   window/logMessage
@@ -290,38 +293,40 @@ Use cases:
 Any callbacks passed directly to `request` methods on a server client will
 have the highest precedence, followed by the `default_callbacks`.
 
-More information about callbacks can be found in |lsp-callbacks|.
+You can override the default handlers,
+- globally: by modifying the `vim.lsp.default_callbacks` table
+- per-client: by passing the {callbacks} table parameter to
+  |vim.lsp.start_client|
 
-================================================================================
+Each handler has this signature: >
-                                                                 *lsp-callbacks*
+
+  function(err, method, params, client_id)
 
 Callbacks are functions which are called in a variety of situations by the
 client. Their signature is `function(err, method, params, client_id)` They can
 be set by the {callbacks} parameter for |vim.lsp.start_client| or via the
 |vim.lsp.default_callbacks|.
 
-This will be called for:
+Handlers are called for:
-- notifications from the server, where `err` will always be `nil`
+- Notifications from the server (`err` is always `nil`).
-- requests initiated by the server. The parameter `err` will be `nil` here as
+- Requests initiated by the server (`err` is always `nil`).
-  well.
+  The handler can respond by returning two values: `result, err`
-  For these, you can respond by returning two values: `result, err` The
+  where `err` must be shaped like an RPC error:
-  err must be in the format of an RPC error, which is
+    `{ code, message, data? }`
-    `{ code, message, data?  }` 
+  You can use |vim.lsp.rpc_response_error()| to create this object.
-  You can use |vim.lsp.rpc_response_error()| to help with creating this object.
+- Handling requests initiated by the client if the request doesn't explicitly
-- as a callback for requests initiated by the client if the request doesn't
+  specify a callback (such as in |vim.lsp.buf_request|).
-  explicitly specify a callback (such as in |vim.lsp.buf_request|).
 
 ================================================================================
-                                                              *vim.lsp.protocol*
+VIM.LSP.PROTOCOL                                              *vim.lsp.protocol*
-vim.lsp.protocol
 
-  Contains constants as described in the Language Server Protocol
+The `vim.lsp.protocol` module provides constants defined in the LSP
-  specification and helper functions for creating protocol related objects.
+specification, and helper functions for creating protocol-related objects.
 
   https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
 
-  Useful examples are `vim.lsp.protocol.ErrorCodes`. These objects allow
+Useful examples are `vim.lsp.protocol.ErrorCodes`. These objects allow reverse
-  reverse lookup by either the number or string name.
+lookup by either the number or string name.
 
   e.g. vim.lsp.protocol.TextDocumentSyncKind.Full == 1
        vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
@@ -428,7 +433,7 @@ To configure omnifunc, add the following in your init.vim:
 >
   " Configure for python
   autocmd Filetype python setl omnifunc=v:lua.vim.lsp.omnifunc
-  
+
   " Or with on_attach
   start_client {
     ...
@@ -436,12 +441,12 @@ To configure omnifunc, add the following in your init.vim:
       vim.api.nvim_buf_set_option(bufnr, 'omnifunc', 'v:lua.vim.lsp.omnifunc')
     end;
   }
-  
+
   " This is optional, but you may find it useful
   autocmd CompleteDone * pclose
 <
 ================================================================================
-                                                             *lsp-vim-functions*
+LSP FUNCTIONS                                                *lsp-vim-functions*
 
 To use the functions from vim, it is recommended to use |v:lua| to interface
 with the Lua functions. No direct vim functions are provided, but the
@@ -461,7 +466,7 @@ request from lua as follows:
   nnoremap <silent> ;td <cmd>lua vim.lsp.buf.type_definition()<CR>
 <
 ================================================================================
-                                                       *lsp-advanced-js-example*
+LSP EXAMPLE                                            *lsp-advanced-js-example*
 
 For more advanced configurations where just filtering by filetype isn't
 sufficient, you can use the `vim.lsp.start_client()` and
@@ -483,7 +488,7 @@ The example will:
     local stat = vim.loop.fs_stat(filename)
     return stat and stat.type == 'directory' or false
   end
-  
+
   local path_sep = vim.loop.os_uname().sysname == "Windows" and "\\" or "/"
   -- Asumes filepath is a file.
   local function dirname(filepath)
@@ -494,11 +499,11 @@ The example will:
     end)
     return result, is_changed
   end
-  
+
   local function path_join(...)
     return table.concat(vim.tbl_flatten {...}, path_sep)
   end
-  
+
   -- Ascend the buffer's path until we find the rootdir.
   -- is_root_path is a function which returns bool
   local function buffer_find_root_dir(bufnr, is_root_path)
@@ -520,7 +525,7 @@ The example will:
       end
     end
   end
-  
+
   -- A table to store our root_dir to client_id lookup. We want one LSP per
   -- root directory, and this is how we assert that.
   local javascript_lsps = {}
@@ -531,14 +536,14 @@ The example will:
     ["typescript"]     = true;
     ["typescript.jsx"] = true;
   }
-  
+
   -- Create a template configuration for a server to start, minus the root_dir
   -- which we will specify later.
   local javascript_lsp_config = {
     name = "javascript";
     cmd = { path_join(os.getenv("JAVASCRIPT_LANGUAGE_SERVER_DIRECTORY"), "lib", "language-server-stdio.js") };
   }
-  
+
   -- This needs to be global so that we can call it from the autocmd.
   function check_start_javascript_lsp()
     local bufnr = vim.api.nvim_get_current_buf()
@@ -555,7 +560,7 @@ The example will:
     end)
     -- We couldn't find a root directory, so ignore this file.
     if not root_dir then return end
-  
+
     -- Check if we have a client alredy or start and store it.
     local client_id = javascript_lsps[root_dir]
     if not client_id then
@@ -569,7 +574,7 @@ The example will:
     -- are already attached.
     vim.lsp.buf_attach_client(bufnr, client_id)
   end
-  
+
   vim.api.nvim_command [[autocmd BufReadPost * lua check_start_javascript_lsp()]]
 <
 

runtime/doc/lua.txt

@@ -876,16 +876,23 @@ tbl_add_reverse_lookup({o})                     *vim.tbl_add_reverse_lookup()*
                 Parameters: ~
                     {o}  table The table to add the reverse to.
 
-list_extend({dst}, {src})                                  *vim.list_extend()*
+list_extend({dst}, {src}, {start}, {finish})               *vim.list_extend()*
                 Extends a list-like table with the values of another list-like
                 table.
 
+                NOTE: This mutates dst!
+
                 Parameters: ~
-                    {dst}  The list which will be modified and appended to.
+                    {dst}     list which will be modified and appended to.
-                    {src}  The list from which values will be inserted.
+                    {src}     list from which values will be inserted.
+                    {start}   Start index on src. defaults to 1
+                    {finish}  Final index on src. defaults to #src
+
+                Return: ~
+                    dst
 
                 See also: ~
-                    |extend()|
+                    |vim.tbl_extend()|
 
 tbl_flatten({t})                                           *vim.tbl_flatten()*
                 Creates a copy of a list-like table such that any nested

runtime/doc/map.txt

@@ -786,7 +786,7 @@ g@{motion}		Call the function set by the 'operatorfunc' option.
 			character of the text.
 			The function is called with one String argument:
 			    "line"	{motion} was |linewise|
-			    "char"	{motion} was |characterwise|
+			    "char"	{motion} was |charwise|
 			    "block"	{motion} was |blockwise-visual|
 			Although "block" would rarely appear, since it can
 			only result from Visual mode where "g@" is not useful.

runtime/doc/message.txt

@@ -679,8 +679,8 @@ no argument has been specified.
   Invalid argument: {arg}
   Duplicate argument: {arg}
 
-An Ex command or function has been executed, but an invalid argument has been
+Ex command or function has been executed, but an invalid argument was
-specified.
+specified.  Or a non-executable command was given to |system()|.
 
 							*E488*  >
   Trailing characters

runtime/doc/motion.txt

@@ -60,11 +60,11 @@ After applying the operator the cursor is mostly left at the start of the text
 that was operated upon.  For example, "yfe" doesn't move the cursor, but "yFe"
 moves the cursor leftwards to the "e" where the yank started.
 
-						*linewise* *characterwise*
+						*linewise* *charwise* *characterwise*
 The operator either affects whole lines, or the characters between the start
 and end position.  Generally, motions that move between lines affect lines
 (are linewise), and motions that move within a line affect characters (are
-characterwise).  However, there are some exceptions.
+charwise).  However, there are some exceptions.
 
 						*exclusive* *inclusive*
 Character motion is either inclusive or exclusive.  When inclusive, the
@@ -106,10 +106,10 @@ This cannot be repeated: >
 	d:if 1<CR>
 	   call search("f")<CR>
 	endif<CR>
-Note that when using ":" any motion becomes characterwise exclusive.
+Note that when using ":" any motion becomes charwise exclusive.
 
 								*forced-motion*
-FORCING A MOTION TO BE LINEWISE, CHARACTERWISE OR BLOCKWISE
+FORCING A MOTION TO BE LINEWISE, CHARWISE OR BLOCKWISE
 
 When a motion is not of the type you would like to use, you can force another
 type by using "v", "V" or CTRL-V just after the operator.
@@ -121,22 +121,22 @@ deletes from the cursor position until the character below the cursor >
 	d<C-V>j
 deletes the character under the cursor and the character below the cursor. >
 
-Be careful with forcing a linewise movement to be used characterwise or
+Be careful with forcing a linewise movement to be used charwise or blockwise,
-blockwise, the column may not always be defined.
+the column may not always be defined.
 
 							*o_v*
 v		When used after an operator, before the motion command: Force
-		the operator to work characterwise, also when the motion is
+		the operator to work charwise, also when the motion is
 		linewise.  If the motion was linewise, it will become
 		|exclusive|.
-		If the motion already was characterwise, toggle
+		If the motion already was charwise, toggle
 		inclusive/exclusive.  This can be used to make an exclusive
 		motion inclusive and an inclusive motion exclusive.
 
 							*o_V*
 V		When used after an operator, before the motion command: Force
 		the operator to work linewise, also when the motion is
-		characterwise.
+		charwise.
 
 							*o_CTRL-V*
 CTRL-V		When used after an operator, before the motion command: Force
@@ -508,36 +508,36 @@ aw			"a word", select [count] words (see |word|).
 			Leading or trailing white space is included, but not
 			counted.
 			When used in Visual linewise mode "aw" switches to
-			Visual characterwise mode.
+			Visual charwise mode.
 
 							*v_iw* *iw*
 iw			"inner word", select [count] words (see |word|).
 			White space between words is counted too.
 			When used in Visual linewise mode "iw" switches to
-			Visual characterwise mode.
+			Visual charwise mode.
 
 							*v_aW* *aW*
 aW			"a WORD", select [count] WORDs (see |WORD|).
 			Leading or trailing white space is included, but not
 			counted.
 			When used in Visual linewise mode "aW" switches to
-			Visual characterwise mode.
+			Visual charwise mode.
 
 							*v_iW* *iW*
 iW			"inner WORD", select [count] WORDs (see |WORD|).
 			White space between words is counted too.
 			When used in Visual linewise mode "iW" switches to
-			Visual characterwise mode.
+			Visual charwise mode.
 
 							*v_as* *as*
 as			"a sentence", select [count] sentences (see
 			|sentence|).
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 							*v_is* *is*
 is			"inner sentence", select [count] sentences (see
 			|sentence|).
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 							*v_ap* *ap*
 ap			"a paragraph", select [count] paragraphs (see
@@ -558,14 +558,14 @@ a[			"a [] block", select [count] '[' ']' blocks.  This
 			goes backwards to the [count] unclosed '[', and finds
 			the matching ']'.  The enclosed text is selected,
 			including the '[' and ']'.
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 i]						*v_i]* *v_i[* *i]* *i[*
 i[			"inner [] block", select [count] '[' ']' blocks.  This
 			goes backwards to the [count] unclosed '[', and finds
 			the matching ']'.  The enclosed text is selected,
 			excluding the '[' and ']'.
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 a)							*v_a)* *a)* *a(*
 a(							*vab* *v_ab* *v_a(* *ab*
@@ -573,54 +573,54 @@ ab			"a block", select [count] blocks, from "[count] [(" to
 			the matching ')', including the '(' and ')' (see
 			|[(|).  Does not include white space outside of the
 			parenthesis.
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 i)							*v_i)* *i)* *i(*
 i(							*vib* *v_ib* *v_i(* *ib*
 ib			"inner block", select [count] blocks, from "[count] [("
 			to the matching ')', excluding the '(' and ')' (see
 			|[(|).
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 a>						*v_a>* *v_a<* *a>* *a<*
 a<			"a <> block", select [count] <> blocks, from the
 			[count]'th unmatched '<' backwards to the matching
 			'>', including the '<' and '>'.
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 i>						*v_i>* *v_i<* *i>* *i<*
 i<			"inner <> block", select [count] <> blocks, from
 			the [count]'th unmatched '<' backwards to the matching
 			'>', excluding the '<' and '>'.
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 						*v_at* *at*
 at			"a tag block", select [count] tag blocks, from the
 			[count]'th unmatched "<aaa>" backwards to the matching
 			"</aaa>", including the "<aaa>" and "</aaa>".
 			See |tag-blocks| about the details.
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 						*v_it* *it*
 it			"inner tag block", select [count] tag blocks, from the
 			[count]'th unmatched "<aaa>" backwards to the matching
 			"</aaa>", excluding the "<aaa>" and "</aaa>".
 			See |tag-blocks| about the details.
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 a}							*v_a}* *a}* *a{*
 a{							*v_aB* *v_a{* *aB*
 aB			"a Block", select [count] Blocks, from "[count] [{" to
 			the matching '}', including the '{' and '}' (see
 			|[{|).
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 i}							*v_i}* *i}* *i{*
 i{							*v_iB* *v_i{* *iB*
 iB			"inner Block", select [count] Blocks, from "[count] [{"
 			to the matching '}', excluding the '{' and '}' (see
 			|[{|).
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 
 a"							*v_aquote* *aquote*
 a'							*v_a'* *a'*
@@ -634,7 +634,7 @@ a`							*v_a`* *a`*
 			start of the line.
 			Any trailing white space is included, unless there is
 			none, then leading white space is included.
-			When used in Visual mode it is made characterwise.
+			When used in Visual mode it is made charwise.
 			Repeating this object in Visual mode another string is
 			included.  A count is currently not used.
 

runtime/doc/starting.txt

@@ -1270,7 +1270,7 @@ exactly four MessagePack objects:
                        Key  Type             Def   Description ~
                        rt   UInteger         0     Register type:
                                                    No  Description ~
-                                                   0   |characterwise-register|
+                                                   0   |charwise-register|
                                                    1   |linewise-register|
                                                    2   |blockwise-register|
                        rw   UInteger         0     Register width. Only valid

runtime/doc/visual.txt

@@ -48,7 +48,7 @@ position.
 ==============================================================================
 2. Starting and stopping Visual mode			*visual-start*
 
-						*v* *characterwise-visual*
+						*v* *charwise-visual*
 [count]v		Start Visual mode per character.
 			With [count] select the same number of characters or
 			lines as used for the last Visual operation, but at
@@ -74,7 +74,7 @@ position.
 
 If you use <Esc>, click the left mouse button or use any command that
 does a jump to another buffer while in Visual mode, the highlighting stops
-and no text is affected.  Also when you hit "v" in characterwise Visual mode,
+and no text is affected.  Also when you hit "v" in charwise Visual mode,
 "CTRL-V" in blockwise Visual mode or "V" in linewise Visual mode.  If you hit
 CTRL-Z the highlighting stops and the editor is suspended or a new shell is
 started |CTRL-Z|.
@@ -477,7 +477,7 @@ Commands in Select mode:
 Otherwise, typed characters are handled as in Visual mode.
 
 When using an operator in Select mode, and the selection is linewise, the
-selected lines are operated upon, but like in characterwise selection.  For
+selected lines are operated upon, but like in charwise selection.  For
 example, when a whole line is deleted, it can later be pasted in the middle of
 a line.
 
@@ -510,7 +510,7 @@ gV			Avoid the automatic reselection of the Visual area
 			selection.
 
 							*gh*
-gh			Start Select mode, characterwise.  This is like "v",
+gh			Start Select mode, charwise.  This is like "v",
 			but starts Select mode instead of Visual mode.
 			Mnemonic: "get highlighted".
 

runtime/lua/vim/shared.lua

@@ -226,16 +226,17 @@ function vim.tbl_add_reverse_lookup(o)
   return o
 end
 
--- Extends a list-like table with the values of another list-like table.
+--- Extends a list-like table with the values of another list-like table.
---
+---
--- NOTE: This *mutates* dst!
+--- NOTE: This mutates dst!
--- @see |extend()|
+---
---
+--@see |vim.tbl_extend()|
--- @param dst list which will be modified and appended to.
+---
--- @param src list from which values will be inserted.
+--@param dst list which will be modified and appended to.
--- @param start Start index on src. defaults to 1
+--@param src list from which values will be inserted.
--- @param finish Final index on src. defaults to #src
+--@param start Start index on src. defaults to 1
--- @returns dst
+--@param finish Final index on src. defaults to #src
+--@returns dst
 function vim.list_extend(dst, src, start, finish)
   vim.validate {
     dst = {dst, 't'};

src/nvim/api/buffer.c

@@ -1013,10 +1013,10 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
 
 /// Returns position for a given extmark id
 ///
-/// @param buffer The buffer handle
+/// @param buffer  Buffer handle, or 0 for current buffer
-/// @param namespace a identifier returned previously with nvim_create_namespace
+/// @param ns_id  Namespace id from |nvim_create_namespace()|
-/// @param id the extmark id
+/// @param id  Extmark id
-/// @param[out] err Details of an error that may have occurred
+/// @param[out] err   Error details, if any
 /// @return (row, col) tuple or empty list () if extmark id was absent
 ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
                                             Integer id, Error *err)
@@ -1044,30 +1044,50 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
   return rv;
 }
 
-/// List extmarks in a range (inclusive)
+/// Gets extmarks in "traversal order" from a |charwise| region defined by
+/// buffer positions (inclusive, 0-indexed |api-indexing|).
 ///
-/// range ends can be specified as (row, col) tuples, as well as extmark
+/// Region can be given as (row,col) tuples, or valid extmark ids (whose
-/// ids in the same namespace. In addition, 0 and -1 works as shorthands
+/// positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
-/// for (0,0) and (-1,-1) respectively, so that all marks in the buffer can be
+/// respectively, thus the following are equivalent:
-/// queried as:
 ///
-///    all_marks = nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
+/// <pre>
+///   nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
+///   nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
+/// </pre>
 ///
-/// If end is a lower position than start, then the range will be traversed
+/// If `end` is less than `start`, traversal works backwards. (Useful
-/// backwards. This is mostly useful with limited amount, to be able to get the
+/// with `limit`, to get the first marks prior to a given position.)
-/// first marks prior to a given position.
 ///
-/// @param buffer The buffer handle
+/// Example:
-/// @param ns_id An id returned previously from nvim_create_namespace
+///
-/// @param start One of:  extmark id, (row, col) or 0, -1 for buffer ends
+/// <pre>
-/// @param end One of: extmark id, (row, col) or 0, -1 for buffer ends
+///   local a   = vim.api
-/// @param opts additional options. Supports the keys:
+///   local pos = a.nvim_win_get_cursor(0)
-///          - amount:  Maximum number of marks to return
+///   local ns  = a.nvim_create_namespace('my-plugin')
-/// @param[out] err Details of an error that may have occurred
+///   -- Create new extmark at line 1, column 1.
-/// @return [[extmark_id, row, col], ...]
+///   local m1  = a.nvim_buf_set_extmark(0, ns, 0, 0, 0, {})
-Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
+///   -- Create new extmark at line 3, column 1.
-                            Object start, Object end, Dictionary opts,
+///   local m2  = a.nvim_buf_set_extmark(0, ns, 0, 2, 0, {})
-                            Error *err)
+///   -- Get extmarks only from line 3.
+///   local ms  = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
+///   -- Get all marks in this buffer + namespace.
+///   local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
+///   print(vim.inspect(ms))
+/// </pre>
+///
+/// @param buffer  Buffer handle, or 0 for current buffer
+/// @param ns_id  Namespace id from |nvim_create_namespace()|
+/// @param start  Start of range, given as (row, col) or valid extmark id
+///               (whose position defines the bound)
+/// @param end  End of range, given as (row, col) or valid extmark id
+///             (whose position defines the bound)
+/// @param opts  Optional parameters. Keys:
+///          - limit:  Maximum number of marks to return
+/// @param[out] err   Error details, if any
+/// @return List of [extmark_id, row, col] tuples in "traversal order".
+Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start,
+                            Object end, Dictionary opts, Error *err)
   FUNC_API_SINCE(7)
 {
   Array rv = ARRAY_DICT_INIT;
@@ -1081,17 +1101,17 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
     api_set_error(err, kErrorTypeValidation, _("Invalid ns_id"));
     return rv;
   }
-  Integer amount = -1;
+  Integer limit = -1;
 
   for (size_t i = 0; i < opts.size; i++) {
     String k = opts.items[i].key;
     Object *v = &opts.items[i].value;
-    if (strequal("amount", k.data)) {
+    if (strequal("limit", k.data)) {
       if (v->type != kObjectTypeInteger) {
-        api_set_error(err, kErrorTypeValidation, "amount is not an integer");
+        api_set_error(err, kErrorTypeValidation, "limit is not an integer");
         return rv;
       }
-      amount = v->data.integer;
+      limit = v->data.integer;
       v->data.integer = LUA_NOREF;
     } else {
       api_set_error(err, kErrorTypeValidation, "unexpected key: %s", k.data);
@@ -1099,7 +1119,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
     }
   }
 
-  if (amount == 0) {
+  if (limit == 0) {
     return rv;
   }
 
@@ -1108,13 +1128,13 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
 
   linenr_T l_lnum;
   colnr_T l_col;
-  if (!set_extmark_index_from_obj(buf, ns_id, start, &l_lnum, &l_col, err)) {
+  if (!extmark_get_index_from_obj(buf, ns_id, start, &l_lnum, &l_col, err)) {
     return rv;
   }
 
   linenr_T u_lnum;
   colnr_T u_col;
-  if (!set_extmark_index_from_obj(buf, ns_id, end, &u_lnum, &u_col, err)) {
+  if (!extmark_get_index_from_obj(buf, ns_id, end, &u_lnum, &u_col, err)) {
     return rv;
   }
 
@@ -1129,9 +1149,8 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
   }
 
 
-  ExtmarkArray marks = extmark_get(buf, (uint64_t)ns_id, l_lnum, l_col,
+  ExtmarkArray marks = extmark_get(buf, (uint64_t)ns_id, l_lnum, l_col, u_lnum,
-                                   u_lnum, u_col, (int64_t)amount,
+                                   u_col, (int64_t)limit, reverse);
-                                   reverse);
 
   for (size_t i = 0; i < kv_size(marks); i++) {
     Array mark = ARRAY_DICT_INIT;
@@ -1146,26 +1165,23 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
   return rv;
 }
 
-/// Create or update an extmark at a position
+/// Creates or updates an extmark.
 ///
-/// If an invalid namespace is given, an error will be raised.
+/// To create a new extmark, pass id=0. The extmark id will be returned.
-///
+//  To move an existing mark, pass its id.
-/// To create a new extmark, pass in id=0. The new extmark id will be
-/// returned. To move an existing mark, pass in its id.
 ///
 /// It is also allowed to create a new mark by passing in a previously unused
 /// id, but the caller must then keep track of existing and unused ids itself.
-/// This is mainly useful over RPC, to avoid needing to wait for the return
+/// (Useful over RPC, to avoid waiting for the return value.)
-/// value.
 ///
-/// @param buffer The buffer handle
+/// @param buffer  Buffer handle, or 0 for current buffer
-/// @param ns_id a identifier returned previously with nvim_create_namespace
+/// @param ns_id  Namespace id from |nvim_create_namespace()|
-/// @param id The extmark's id or 0 to create a new mark.
+/// @param id  Extmark id, or 0 to create new
-/// @param line The row to set the extmark to.
+/// @param line  Line number where to place the mark
-/// @param col The column to set the extmark to.
+/// @param col  Column where to place the mark
-/// @param opts Optional parameters. Currently not used.
+/// @param opts  Optional parameters. Currently not used.
-/// @param[out] err Details of an error that may have occurred
+/// @param[out]  err   Error details, if any
-/// @return the id of the extmark.
+/// @return Id of the created/updated extmark
 Integer nvim_buf_set_extmark(Buffer buffer, Integer ns_id, Integer id,
                              Integer line, Integer col,
                              Dictionary opts, Error *err)
@@ -1217,13 +1233,13 @@ Integer nvim_buf_set_extmark(Buffer buffer, Integer ns_id, Integer id,
   return (Integer)id_num;
 }
 
-/// Remove an extmark
+/// Removes an extmark.
 ///
-/// @param buffer The buffer handle
+/// @param buffer Buffer handle, or 0 for current buffer
-/// @param ns_id a identifier returned previously with nvim_create_namespace
+/// @param ns_id Namespace id from |nvim_create_namespace()|
-/// @param id The extmarks's id
+/// @param id Extmark id
-/// @param[out] err Details of an error that may have occurred
+/// @param[out] err   Error details, if any
-/// @return true on success, false if the extmark was not found.
+/// @return true if the extmark was found, else false
 Boolean nvim_buf_del_extmark(Buffer buffer,
                              Integer ns_id,
                              Integer id,
@@ -1309,7 +1325,8 @@ Integer nvim_buf_add_highlight(Buffer buffer,
   return ns_id;
 }
 
-/// Clears namespaced objects, highlights and virtual text, from a line range
+/// Clears namespaced objects (highlights, extmarks, virtual text) from
+/// a region.
 ///
 /// Lines are 0-indexed. |api-indexing|  To clear the namespace in the entire
 /// buffer, specify line_start=0 and line_end=-1.

src/nvim/api/private/helpers.c

@@ -1512,7 +1512,7 @@ ArrayOf(Dictionary) keymap_array(String mode, buf_T *buf)
 // If throw == true then an error will be raised if nothing
 // was found
 // Returns NULL if something went wrong
-Extmark *extmark_from_id_or_pos(Buffer buffer, Integer namespace, Object id,
+Extmark *extmark_from_id_or_pos(Buffer buffer, Integer ns, Object id,
                                 Error *err, bool throw)
 {
   buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -1536,7 +1536,7 @@ Extmark *extmark_from_id_or_pos(Buffer buffer, Integer namespace, Object id,
       }
       return NULL;
     }
-    extmark = extmark_from_pos(buf, (uint64_t)namespace, row, col);
+    extmark = extmark_from_pos(buf, (uint64_t)ns, row, col);
   } else if (id.type != kObjectTypeInteger) {
     if (throw) {
       api_set_error(err, kErrorTypeValidation,
@@ -1550,7 +1550,7 @@ Extmark *extmark_from_id_or_pos(Buffer buffer, Integer namespace, Object id,
     return NULL;
   } else {
     extmark = extmark_from_id(buf,
-                              (uint64_t)namespace,
+                              (uint64_t)ns,
                               (uint64_t)id.data.integer);
   }
 
@@ -1572,17 +1572,17 @@ bool ns_initialized(uint64_t ns)
   return ns < (uint64_t)next_namespace_id;
 }
 
-/// Get line and column from extmark object
+/// Gets the line and column of an extmark.
 ///
-/// Extmarks may be queried from position or name or even special names
+/// Extmarks may be queried by position, name or even special names
-/// in the future such as "cursor". This function sets the line and col
+/// in the future such as "cursor".
-/// to make the extmark functions recognize what's required
 ///
-/// @param[out] lnum lnum to be set
+/// @param[out] lnum extmark line
-/// @param[out] colnr col to be set
+/// @param[out] colnr extmark column
-bool set_extmark_index_from_obj(buf_T *buf, Integer namespace,
+///
-                                Object obj, linenr_T *lnum, colnr_T *colnr,
+/// @return true if the extmark was found, else false
-                                Error *err)
+bool extmark_get_index_from_obj(buf_T *buf, Integer ns, Object obj, linenr_T
+                                *lnum, colnr_T *colnr, Error *err)
 {
   // Check if it is mark id
   if (obj.type == kObjectTypeInteger) {
@@ -1600,7 +1600,7 @@ bool set_extmark_index_from_obj(buf_T *buf, Integer namespace,
       return false;
     }
 
-    Extmark *extmark = extmark_from_id(buf, (uint64_t)namespace, (uint64_t)id);
+    Extmark *extmark = extmark_from_id(buf, (uint64_t)ns, (uint64_t)id);
     if (extmark) {
       *lnum = extmark->line->lnum;
       *colnr = extmark->col;

src/nvim/api/vim.c

@@ -1291,7 +1291,7 @@ theend:
 /// @param lines  |readfile()|-style list of lines. |channel-lines|
 /// @param type  Edit behavior: any |getregtype()| result, or:
 ///              - "b" |blockwise-visual| mode (may include width, e.g. "b3")
-///              - "c" |characterwise| mode
+///              - "c" |charwise| mode
 ///              - "l" |linewise| mode
 ///              - ""  guess by contents, see |setreg()|
 /// @param after  Insert after cursor (like |p|), or before (like |P|).

src/nvim/normal.c

@@ -1422,12 +1422,12 @@ void do_pending_operator(cmdarg_T *cap, int old_col, bool gui_yank)
       if (oap->motion_type == kMTLineWise) {
         oap->inclusive = false;
       } else if (oap->motion_type == kMTCharWise) {
-        // If the motion already was characterwise, toggle "inclusive"
+        // If the motion already was charwise, toggle "inclusive"
         oap->inclusive = !oap->inclusive;
       }
       oap->motion_type = kMTCharWise;
     } else if (oap->motion_force == Ctrl_V) {
-      // Change line- or characterwise motion into Visual block mode.
+      // Change line- or charwise motion into Visual block mode.
       if (!VIsual_active) {
         VIsual_active = true;
         VIsual = oap->start;
@@ -1516,7 +1516,7 @@ void do_pending_operator(cmdarg_T *cap, int old_col, bool gui_yank)
       }
 
       // In Select mode, a linewise selection is operated upon like a
-      // characterwise selection.
+      // charwise selection.
       // Special case: gH<Del> deletes the last line.
       if (VIsual_select && VIsual_mode == 'V'
           && cap->oap->op_type != OP_DELETE) {
@@ -4588,7 +4588,7 @@ static void nv_colon(cmdarg_T *cap)
     nv_operator(cap);
   } else {
     if (cap->oap->op_type != OP_NOP) {
-      // Using ":" as a movement is characterwise exclusive.
+      // Using ":" as a movement is charwise exclusive.
       cap->oap->motion_type = kMTCharWise;
       cap->oap->inclusive = false;
     } else if (cap->count0 && !is_cmdkey) {
@@ -6372,8 +6372,8 @@ static void nv_visual(cmdarg_T *cap)
   if (cap->cmdchar == Ctrl_Q)
     cap->cmdchar = Ctrl_V;
 
-  /* 'v', 'V' and CTRL-V can be used while an operator is pending to make it
+  // 'v', 'V' and CTRL-V can be used while an operator is pending to make it
-   * characterwise, linewise, or blockwise. */
+  // charwise, linewise, or blockwise.
   if (cap->oap->op_type != OP_NOP) {
     motion_force = cap->oap->motion_force = cap->cmdchar;
     finish_op = false;          // operator doesn't finish now but later
@@ -7887,15 +7887,17 @@ static void nv_put_opt(cmdarg_T *cap, bool fix_indent)
         cap->oap->regname = regname;
       }
 
-      /* When deleted a linewise Visual area, put the register as
+      // When deleted a linewise Visual area, put the register as
-       * lines to avoid it joined with the next line.  When deletion was
+      // lines to avoid it joined with the next line.  When deletion was
-       * characterwise, split a line when putting lines. */
+      // charwise, split a line when putting lines.
-      if (VIsual_mode == 'V')
+      if (VIsual_mode == 'V') {
         flags |= PUT_LINE;
-      else if (VIsual_mode == 'v')
+      } else if (VIsual_mode == 'v') {
         flags |= PUT_LINE_SPLIT;
-      if (VIsual_mode == Ctrl_V && dir == FORWARD)
+      }
+      if (VIsual_mode == Ctrl_V && dir == FORWARD) {
         flags |= PUT_LINE_FORWARD;
+      }
       dir = BACKWARD;
       if ((VIsual_mode != 'V'
            && curwin->w_cursor.col < curbuf->b_op_start.col)

src/nvim/ops.c

@@ -5204,8 +5204,7 @@ void write_reg_contents_lst(int name, char_u **strings,
 
 /// write_reg_contents_ex - store `str` in register `name`
 ///
-/// If `str` ends in '\n' or '\r', use linewise, otherwise use
+/// If `str` ends in '\n' or '\r', use linewise, otherwise use charwise.
-/// characterwise.
 ///
 /// @warning when `name` is '/', `len` and `must_append` are ignored. This
 ///          means that `str` MUST be NUL-terminated.

src/nvim/state.c

@@ -156,7 +156,7 @@ char *get_mode(void)
     buf[0] = 'n';
     if (finish_op) {
       buf[1] = 'o';
-      // to be able to detect force-linewise/blockwise/characterwise operations
+      // to be able to detect force-linewise/blockwise/charwise operations
       buf[2] = (char)motion_force;
     } else if (restart_edit == 'I' || restart_edit == 'R'
                || restart_edit == 'V') {

test/functional/api/mark_extended_spec.lua

@@ -36,7 +36,7 @@ local function get_extmarks(ns_id, start, end_, opts)
   return curbufmeths.get_extmarks(ns_id, start, end_, opts)
 end
 
-describe('Extmarks buffer api', function()
+describe('API/extmarks', function()
   local screen
   local marks, positions, ns_string2, ns_string, init_text, row, col
   local ns, ns2
@@ -153,26 +153,26 @@ describe('Extmarks buffer api', function()
     end
 
     -- next with mark id
-    rv = get_extmarks(ns, marks[1], {-1, -1}, {amount=1})
+    rv = get_extmarks(ns, marks[1], {-1, -1}, {limit=1})
     eq({{marks[1], positions[1][1], positions[1][2]}}, rv)
-    rv = get_extmarks(ns, marks[2], {-1, -1}, {amount=1})
+    rv = get_extmarks(ns, marks[2], {-1, -1}, {limit=1})
     eq({{marks[2], positions[2][1], positions[2][2]}}, rv)
     -- next with positional when mark exists at position
-    rv = get_extmarks(ns, positions[1], {-1, -1}, {amount=1})
+    rv = get_extmarks(ns, positions[1], {-1, -1}, {limit=1})
     eq({{marks[1], positions[1][1], positions[1][2]}}, rv)
     -- next with positional index (no mark at position)
-    rv = get_extmarks(ns, {positions[1][1], positions[1][2] +1}, {-1, -1}, {amount=1})
+    rv = get_extmarks(ns, {positions[1][1], positions[1][2] +1}, {-1, -1}, {limit=1})
     eq({{marks[2], positions[2][1], positions[2][2]}}, rv)
     -- next with Extremity index
-    rv = get_extmarks(ns, {0,0}, {-1, -1}, {amount=1})
+    rv = get_extmarks(ns, {0,0}, {-1, -1}, {limit=1})
     eq({{marks[1], positions[1][1], positions[1][2]}}, rv)
 
     -- nextrange with mark id
     rv = get_extmarks(ns, marks[1], marks[3])
     eq({marks[1], positions[1][1], positions[1][2]}, rv[1])
     eq({marks[2], positions[2][1], positions[2][2]}, rv[2])
-    -- nextrange with amount
+    -- nextrange with `limit`
-    rv = get_extmarks(ns, marks[1], marks[3], {amount=2})
+    rv = get_extmarks(ns, marks[1], marks[3], {limit=2})
     eq(2, table.getn(rv))
     -- nextrange with positional when mark exists at position
     rv = get_extmarks(ns, positions[1], positions[3])
@@ -196,18 +196,18 @@ describe('Extmarks buffer api', function()
     eq({{marks[3], positions[3][1], positions[3][2]}}, rv)
 
     -- prev with mark id
-    rv = get_extmarks(ns, marks[3], {0, 0}, {amount=1})
+    rv = get_extmarks(ns, marks[3], {0, 0}, {limit=1})
     eq({{marks[3], positions[3][1], positions[3][2]}}, rv)
-    rv = get_extmarks(ns, marks[2], {0, 0}, {amount=1})
+    rv = get_extmarks(ns, marks[2], {0, 0}, {limit=1})
     eq({{marks[2], positions[2][1], positions[2][2]}}, rv)
     -- prev with positional when mark exists at position
-    rv = get_extmarks(ns, positions[3], {0, 0}, {amount=1})
+    rv = get_extmarks(ns, positions[3], {0, 0}, {limit=1})
     eq({{marks[3], positions[3][1], positions[3][2]}}, rv)
     -- prev with positional index (no mark at position)
-    rv = get_extmarks(ns, {positions[1][1], positions[1][2] +1}, {0, 0}, {amount=1})
+    rv = get_extmarks(ns, {positions[1][1], positions[1][2] +1}, {0, 0}, {limit=1})
     eq({{marks[1], positions[1][1], positions[1][2]}}, rv)
     -- prev with Extremity index
-    rv = get_extmarks(ns, {-1,-1}, {0,0}, {amount=1})
+    rv = get_extmarks(ns, {-1,-1}, {0,0}, {limit=1})
     eq({{marks[3], positions[3][1], positions[3][2]}}, rv)
 
     -- prevrange with mark id
@@ -215,8 +215,8 @@ describe('Extmarks buffer api', function()
     eq({marks[3], positions[3][1], positions[3][2]}, rv[1])
     eq({marks[2], positions[2][1], positions[2][2]}, rv[2])
     eq({marks[1], positions[1][1], positions[1][2]}, rv[3])
-    -- prevrange with amount
+    -- prevrange with limit
-    rv = get_extmarks(ns, marks[3], marks[1], {amount=2})
+    rv = get_extmarks(ns, marks[3], marks[1], {limit=2})
     eq(2, table.getn(rv))
     -- prevrange with positional when mark exists at position
     rv = get_extmarks(ns, positions[3], positions[1])
@@ -241,7 +241,7 @@ describe('Extmarks buffer api', function()
     eq({{marks[1], positions[1][1], positions[1][2]}}, rv)
   end)
 
-  it('querying for information with amount #extmarks', function()
+  it('querying for information with limit #extmarks', function()
     -- add some more marks
     for i, m in ipairs(marks) do
       if positions[i] ~= nil then
@@ -250,19 +250,19 @@ describe('Extmarks buffer api', function()
       end
     end
 
-    local rv = get_extmarks(ns, {0, 0}, {-1, -1}, {amount=1})
+    local rv = get_extmarks(ns, {0, 0}, {-1, -1}, {limit=1})
     eq(1, table.getn(rv))
-    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {amount=2})
+    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {limit=2})
     eq(2, table.getn(rv))
-    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {amount=3})
+    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {limit=3})
     eq(3, table.getn(rv))
 
     -- now in reverse
-    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {amount=1})
+    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {limit=1})
     eq(1, table.getn(rv))
-    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {amount=2})
+    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {limit=2})
     eq(2, table.getn(rv))
-    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {amount=3})
+    rv = get_extmarks(ns, {0, 0}, {-1, -1}, {limit=3})
     eq(3, table.getn(rv))
   end)
 
@@ -295,9 +295,9 @@ describe('Extmarks buffer api', function()
        rv)
   end)
 
-  it('get_marks amount 0 returns nothing #extmarks', function()
+  it('get_marks limit=0 returns nothing #extmarks', function()
     set_extmark(ns, marks[1], positions[1][1], positions[1][2])
-    local rv = get_extmarks(ns, {-1, -1}, {-1, -1}, {amount=0})
+    local rv = get_extmarks(ns, {-1, -1}, {-1, -1}, {limit=0})
     eq({}, rv)
   end)
 
@@ -730,7 +730,7 @@ describe('Extmarks buffer api', function()
     -- Test updates
     feed('o<esc>')
     set_extmark(ns, marks[1], positions[1][1], positions[1][2])
-    rv = get_extmarks(ns, marks[1], marks[1], {amount=1})
+    rv = get_extmarks(ns, marks[1], marks[1], {limit=1})
     eq(1, table.getn(rv))
     feed("u")
     feed("<c-r>")
@@ -771,23 +771,23 @@ describe('Extmarks buffer api', function()
     set_extmark(ns2, marks[2], positions[2][1], positions[2][2])
     set_extmark(ns2, marks[3], positions[3][1], positions[3][2])
 
-    -- get_next (amount set)
+    -- get_next (limit set)
-    rv = get_extmarks(ns, {0, 0}, positions[2], {amount=1})
+    rv = get_extmarks(ns, {0, 0}, positions[2], {limit=1})
     eq(1, table.getn(rv))
-    rv = get_extmarks(ns2, {0, 0}, positions[2], {amount=1})
+    rv = get_extmarks(ns2, {0, 0}, positions[2], {limit=1})
     eq(1, table.getn(rv))
-    -- get_prev (amount set)
+    -- get_prev (limit set)
-    rv = get_extmarks(ns, positions[1], {0, 0}, {amount=1})
+    rv = get_extmarks(ns, positions[1], {0, 0}, {limit=1})
     eq(1, table.getn(rv))
-    rv = get_extmarks(ns2, positions[1], {0, 0}, {amount=1})
+    rv = get_extmarks(ns2, positions[1], {0, 0}, {limit=1})
     eq(1, table.getn(rv))
 
-    -- get_next (amount not set)
+    -- get_next (no limit)
     rv = get_extmarks(ns, positions[1], positions[2])
     eq(2, table.getn(rv))
     rv = get_extmarks(ns2, positions[1], positions[2])
     eq(2, table.getn(rv))
-    -- get_prev (amount not set)
+    -- get_prev (no limit)
     rv = get_extmarks(ns, positions[2], positions[1])
     eq(2, table.getn(rv))
     rv = get_extmarks(ns2, positions[2], positions[1])
@@ -1250,7 +1250,7 @@ describe('Extmarks buffer api', function()
     eq("col value outside range", pcall_err(set_extmark, ns, marks[1], 0, invalid_col))
   end)
 
-  it('when line > line_count, throw error #extmarks', function()
+  it('fails when line > line_count #extmarks', function()
     local invalid_col = init_text:len() + 1
     local invalid_lnum = 3
     eq('line value outside range', pcall_err(set_extmark, ns, marks[1], invalid_lnum, invalid_col))
@@ -1258,10 +1258,9 @@ describe('Extmarks buffer api', function()
   end)
 
   it('bug from check_col in extmark_set #extmarks_sub', function()
-    -- This bug was caused by extmark_set always using
+    -- This bug was caused by extmark_set always using check_col. check_col
-    -- check_col. check_col always uses the current buffer.
+    -- always uses the current buffer. This wasn't working during undo so we
-    -- This wasn't working during undo so we now use
+    -- now use check_col and check_lnum only when they are required.
-    -- check_col and check_lnum only when they are required.
     feed('A<cr>67890<cr>xx<esc>')
     feed('A<cr>12345<cr>67890<cr>xx<esc>')
     set_extmark(ns, marks[1], 3, 4)

test/functional/api/proc_spec.lua

@@ -10,7 +10,7 @@ local request = helpers.request
 local retry = helpers.retry
 local NIL = helpers.NIL
 
-describe('api', function()
+describe('API', function()
   before_each(clear)
 
   describe('nvim_get_proc_children', function()

test/functional/cmdline/ctrl_r_spec.lua

@@ -15,7 +15,7 @@ describe('cmdline CTRL-R', function()
     -- <CR> inserted between lines, NOT after the final line.
     eq('line1abc\rline2somemoretext', funcs.getcmdline())
 
-    -- Yank 2 lines characterwise, then paste to cmdline.
+    -- Yank 2 lines charwise, then paste to cmdline.
     feed([[<C-\><C-N>gg05lyvj:<C-R>0]])
     -- <CR> inserted between lines, NOT after the final line.
     eq('abc\rline2', funcs.getcmdline())

test/functional/normal/put_spec.lua

@@ -307,7 +307,7 @@ describe('put command', function()
   -- }}}
 
   -- Conversion functions {{{
-  local function convert_characterwise(expect_base, conversion_table,
+  local function convert_charwise(expect_base, conversion_table,
                                        virtualedit_end, visual_put)
     expect_base = dedent(expect_base)
     -- There is no difference between 'P' and 'p' when VIsual_active
@@ -335,7 +335,7 @@ describe('put command', function()
       expect_base = expect_base:gsub('(test_stringx?)"', '%1.')
     end
     return expect_base
-  end -- convert_characterwise()
+  end -- convert_charwise()
 
   local function make_back(string)
     local prev_line
@@ -500,7 +500,7 @@ describe('put command', function()
   local function run_normal_mode_tests(test_string, base_map, extra_setup,
                                        virtualedit_end, selection_string)
     local function convert_closure(e, c)
-      return convert_characterwise(e, c, virtualedit_end, selection_string)
+      return convert_charwise(e, c, virtualedit_end, selection_string)
     end
     local function expect_normal_creator(expect_base, conversion_table)
       local test_expect = expect_creator(convert_closure, expect_base, conversion_table)