doc + extmarks tweaks #11421

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

6 files changed, 108 insertions, 90 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index a5f8b0974e..448ade5e4b 100644
--- a/src/nvim/api/buffer.c
+++ b/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 namespace a identifier returned previously with nvim_create_namespace
-/// @param id the extmark id
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer  Buffer handle, or 0 for current buffer
+/// @param ns_id  Namespace id from |nvim_create_namespace()|
+/// @param id  Extmark id
+/// @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)
-///
-/// range ends can be specified as (row, col) tuples, as well as extmark
-/// ids in the same namespace. In addition, 0 and -1 works as shorthands
-/// for (0,0) and (-1,-1) respectively, so that all marks in the buffer can be
-/// queried as:
-///
-///    all_marks = nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
-///
-/// If end is a lower position than start, then the range will be traversed
-/// backwards. This is mostly useful with limited amount, to be able to get the
-/// first marks prior to a given position.
-///
-/// @param buffer The buffer handle
-/// @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
-/// @param end One of: extmark id, (row, col) or 0, -1 for buffer ends
-/// @param opts additional options. Supports the keys:
-///          - amount:  Maximum number of marks to return
-/// @param[out] err Details of an error that may have occurred
-/// @return [[extmark_id, row, col], ...]
-Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
-                            Object start, Object end, Dictionary opts,
-                            Error *err)
+/// Gets extmarks in "traversal order" from a |charwise| region defined by
+/// buffer positions (inclusive, 0-indexed |api-indexing|).
+///
+/// Region can be given as (row,col) tuples, or valid extmark ids (whose
+/// positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
+/// respectively, thus the following are equivalent:
+///
+/// <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 less than `start`, traversal works backwards. (Useful
+/// with `limit`, to get the first marks prior to a given position.)
+///
+/// Example:
+///
+/// <pre>
+///   local a   = vim.api
+///   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))
+/// </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,
-                                   u_lnum, u_col, (int64_t)amount,
-                                   reverse);
+  ExtmarkArray marks = extmark_get(buf, (uint64_t)ns_id, l_lnum, l_col, u_lnum,
+                                   u_col, (int64_t)limit, 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 in id=0. The new extmark id will be
-/// returned. To move an existing mark, pass in its id.
+/// To create a new extmark, pass id=0. The extmark id will be returned.
+//  To move an existing mark, pass 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
-/// value.
-///
-/// @param buffer The buffer handle
-/// @param ns_id a identifier returned previously with nvim_create_namespace
-/// @param id The extmark's id or 0 to create a new mark.
-/// @param line The row to set the extmark to.
-/// @param col The column to set the extmark to.
-/// @param opts Optional parameters. Currently not used.
-/// @param[out] err Details of an error that may have occurred
-/// @return the id of the extmark.
+/// (Useful over RPC, to avoid waiting for the return value.)
+///
+/// @param buffer  Buffer handle, or 0 for current buffer
+/// @param ns_id  Namespace id from |nvim_create_namespace()|
+/// @param id  Extmark id, or 0 to create new
+/// @param line  Line number where to place the mark
+/// @param col  Column where to place the mark
+/// @param opts  Optional parameters. Currently not used.
+/// @param[out]  err   Error details, if any
+/// @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 ns_id a identifier returned previously with nvim_create_namespace
-/// @param id The extmarks's id
-/// @param[out] err Details of an error that may have occurred
-/// @return true on success, false if the extmark was not found.
+/// @param buffer Buffer handle, or 0 for current buffer
+/// @param ns_id Namespace id from |nvim_create_namespace()|
+/// @param id Extmark id
+/// @param[out] err   Error details, if any
+/// @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.
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index fbfdb27827..b8d62e42a1 100644
--- a/src/nvim/api/private/helpers.c
+++ b/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
-/// in the future such as "cursor". This function sets the line and col
-/// to make the extmark functions recognize what's required
+/// Extmarks may be queried by position, name or even special names
+/// in the future such as "cursor".
 ///
-/// @param[out] lnum lnum to be set
-/// @param[out] colnr col to be set
-bool set_extmark_index_from_obj(buf_T *buf, Integer namespace,
-                                Object obj, linenr_T *lnum, colnr_T *colnr,
-                                Error *err)
+/// @param[out] lnum extmark line
+/// @param[out] colnr extmark column
+///
+/// @return true if the extmark was found, else false
+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;
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 3535bc3186..9adc61b843 100644
--- a/src/nvim/api/vim.c
+++ b/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|).
diff --git a/src/nvim/normal.c b/src/nvim/normal.c
index 2ef2c3101f..b9dbcc6805 100644
--- a/src/nvim/normal.c
+++ b/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
-   * characterwise, linewise, or blockwise. */
+  // 'v', 'V' and CTRL-V can be used while an operator is pending to make it
+  // 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
-       * lines to avoid it joined with the next line.  When deletion was
-       * characterwise, split a line when putting lines. */
-      if (VIsual_mode == 'V')
+      // When deleted a linewise Visual area, put the register as
+      // lines to avoid it joined with the next line.  When deletion was
+      // charwise, split a line when putting lines.
+      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)
diff --git a/src/nvim/ops.c b/src/nvim/ops.c
index f2d35d5e43..294c65ca03 100644
--- a/src/nvim/ops.c
+++ b/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
-/// characterwise.
+/// If `str` ends in '\n' or '\r', use linewise, otherwise use charwise.
 ///
 /// @warning when `name` is '/', `len` and `must_append` are ignored. This
 ///          means that `str` MUST be NUL-terminated.
diff --git a/src/nvim/state.c b/src/nvim/state.c
index 81bc078a88..b195c1d96b 100644
--- a/src/nvim/state.c
+++ b/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') {