doc [ci skip]

runtime/doc/api.txt

@@ -441,38 +441,39 @@ Example: create a float with scratch buffer: >
 ==============================================================================
 Extended marks						   *api-extended-marks*
 
-An extended mark (extmark) represents a buffer annotation that follows
+Extended marks (extmarks) represent buffer annotations that track text changes
-movements as the buffer changes. They could be used to represent cursors,
+in the buffer. They could be used to represent cursors, folds, misspelled
-folds, misspelled words, and anything else that needs to track a logical
+words, and anything else that needs to track a logical location in the buffer
-location in the buffer over time.
+over time.
 
 Example:
 
-We will set an extmark at the first row and third column. As the API is zero-
+We will set an extmark at the first row and third column. |api-indexing| is
-indexed, use row and column counts 0 and 2:
+zero-indexed, so we use row=0 and column=2. Passing id=0 creates a new mark
+and returns the id: >
 
-`let g:mark_ns = nvim_create_namespace('myplugin')`
+    let g:mark_ns = nvim_create_namespace('myplugin')
-`let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 0, 2)`
+    let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 0, 2, {})
 
-Passing in id=0 creates a new mark and returns the id. we can look-up a mark
+We can get a mark by its id: >
-by its id:
 
-`echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id)`
+    echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id)
-=> [0, 2]
+    => [0, 2]
 
-Or we can look-up all marks in a buffer for our namespace (or by a range):
+We can get all marks in a buffer for our namespace (or by a range): >
-`echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, -1)`
-=> [[1, 0, 2]]
 
-Deleting the text all around an extended mark does not remove it. If you want
+    echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, -1)
-to remove an extended mark, use the |nvim_buf_del_extmark()| function.
+    => [[1, 0, 2]]
 
-The namespace ensures your plugin doesn't have to deal with extmarks created
+Deleting all text surrounding an extmark does not remove the extmark. To
-by another plugin.
+remove an extmark use |nvim_buf_del_extmark()|.
 
-Mark positions changed by an edit will be restored on undo/redo. Creating and
+Namespaces allow your plugin to manage only its own extmarks, ignoring those
-deleting marks doesn't count as a buffer change on itself, i e new undo
+created by another plugin.
-states will not be created only for marks.
+
+Extmark positions changed by an edit will be restored on undo/redo. Creating
+and deleting extmarks is not a buffer change, thus new undo states are not
+created for extmark changes.
 
 ==============================================================================
 Global Functions                                                  *api-global*
@@ -1820,10 +1821,10 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
                     {upper}   One of: extmark id, (row, col) or 0, -1 for
                               buffer ends
                     {opts}    additional options. Supports the keys:
-                              • amount: Maximum number of marks to return              •
+                              • amount: Maximum number of marks to return
 
                 Return: ~
-                    [[nsmark_id, row, col], ...]
+                    [[extmark_id, row, col], ...]
 
                                                       *nvim_buf_set_extmark()*
 nvim_buf_set_extmark({buffer}, {ns_id}, {id}, {line}, {col}, {opts})

src/nvim/api/buffer.c

@@ -1058,7 +1058,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
 /// @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 [[nsmark_id, row, col], ...]
+/// @return [[extmark_id, row, col], ...]
 Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
                             Object start, Object end, Dictionary opts,
                             Error *err)

src/nvim/ex_cmds.c

@@ -3457,9 +3457,9 @@ static buf_T *do_sub(exarg_T *eap, proftime_T timeout,
   linenr_T newline_in_pat = 0;
   linenr_T newline_in_sub = 0;
 
-  // inccomand tests fail without this check
+  // inccommand tests fail without this check
   if (!preview) {
-    // Requried for Undo to work for nsmarks,
+    // Required for Undo to work for extmarks.
     u_save_cursor();
   }