docs: extmarks indexing #15311

ref #11456

runtime/doc/api.txt

@@ -134,8 +134,8 @@ lines, 0-based columns):
     |nvim_win_get_cursor()|
     |nvim_win_set_cursor()|
 
-Exception: the following API functions use |extmarks| indexing (0-based lines,
+Exception: the following API functions use |extmarks| indexing (0-based
-0-based columns end-inclusive):
+indices, end-inclusive):
 
     |nvim_buf_del_extmark()|
     |nvim_buf_get_extmark_by_id()|
@@ -447,84 +447,73 @@ Example: create a float with scratch buffer: >
 Extended marks					*api-extended-marks* *extmarks*
 
 Extended marks (extmarks) represent buffer annotations that track text changes
-in the buffer. They could be used to represent cursors, folds, misspelled
+in the buffer. They can represent cursors, folds, misspelled words, anything
-words, and anything else that needs to track a logical location in the buffer
+that needs to track a logical location in the buffer over time. |api-indexing|
-over time. It is useful to think of an extmark position to be in the space
-between characters.
 
-Extmarks use |api-indexing|, and you can think of them as cursor positions.
+Extmark position works like "bar" cursor: it exists between characters. Thus
-For example, an extmark at position 1 exists between the first and second
+the maximum extmark index on a line is 1 more than the character index: >
-character on a line, similar to a bar cursor. For that reason, the maximum
-extmark index on a line is 1 larger than the character index: >
 
-     f o o b a r  <-- line contents (with spaces for illustration purposes)
+     f o o b a r      line contents
-     0 1 2 3 4 5  <-- character positions (0-based)
+     0 1 2 3 4 5      character positions (0-based)
-    0 1 2 3 4 5 6 <-- extmark positions (0-based)
+    0 1 2 3 4 5 6     extmark positions (0-based)
 
-Note that extmarks have "forward gravity": If you place the cursor directly on
+Extmarks have "forward gravity": if you place the cursor directly on an
-an extmark position and enter some text, the extmark gets pushed forward. >
+extmark position and enter some text, the extmark migrates forward. >
 
-     f o o|b a r  <-- line (| = cursor)
+     f o o|b a r      line (| = cursor)
-          3       <-- extmark
+          3           extmark
 
-     (Now add "z" at cursor position):
+     f o o z|b a r    line (| = cursor)
+            4         extmark (after typing "z")
 
-     f o o z|b a r  <-- line (| = cursor)
+If an extmark is on the last index of a line and you inputsa newline at that
-            4       <-- extmark
+point, the extmark will accordingly migrate to the next line: >
 
-If your extmark is on the last possible index of a line (7 in the above
+     f o o z b a r|   line (| = cursor)
-"foozbar" example) and you enter a newline at that point, the extmark will
+                  7   extmark
-accordingly be pushed to the next line: >
 
-     f o o z b a r|  <-- line (| = cursor)
+     f o o z b a r    first line
-                  7  <-- extmark
+                      extmarks (none present)
-
+     |                second line (| = cursor)
-     (Now add <cr> at cursor position):
+     0                extmark (after typing <CR>)
-
-     f o o z b a r  <-- first line
-                    <-- extmarks (none present)
-     |              <-- second line (| = cursor)
-     0              <-- new extmark position
 
 
 Example:
 
-We will set an extmark at the first row and third column. |api-indexing| is
+Let's set an extmark at the first row (row=0) and third column (column=2).
-zero-indexed, so we use row=0 and column=2. Passing id=0 creates a new mark
+|api-indexing| Passing id=0 creates a new mark and returns the id: >
-and returns the id: >
 
       01 2345678
     0 ex|ample..
-<        ^ This is the extmark position
+<        ^ extmark position
 >
     let g:mark_ns = nvim_create_namespace('myplugin')
     let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {})
 <
-We can get a mark by its id: >
+We can get the mark by its id: >
 
     echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
     => [0, 2]
 
-We can get all marks in a buffer for our namespace (or by a range): >
+We can get all marks in a buffer by |namespace| (or by a range): >
 
     echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, {})
     => [[1, 0, 2]]
 
-Deleting all text surrounding an extmark does not remove the extmark. To
+Deleting all surrounding text does NOT remove an extmark! To remove extmarks
-remove an extmark use |nvim_buf_del_extmark()|. Deleting "x" in our example
+use |nvim_buf_del_extmark()|. Deleting "x" in our example: >
-would result in the following: >
 
       0 12345678
     0 e|ample..
-<       ^ This is the extmark position
+<       ^ extmark position
 >
     echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
     => [0, 1]
 <
-    Note: An extmark "gravity" is the direction it will be shifted after a
+    Note: Extmark "gravity" decides how it will shift after a text edit.
-    text edit. See |nvim_buf_set_extmark()| for more information.
+          See |nvim_buf_set_extmark()|
 
-Namespaces allow your plugin to manage only its own extmarks, ignoring those
+Namespaces allow any plugin to manage only its own extmarks, ignoring those
 created by another plugin.
 
 Extmark positions changed by an edit will be restored on undo/redo. Creating

src/nvim/api/vim.c

@@ -1551,7 +1551,7 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
   }
 }
 
-/// Creates a new namespace, or gets an existing one.
+/// Creates a new *namespace*, or gets an existing one.
 ///
 /// Namespaces are used for buffer highlights and virtual text, see
 /// |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|.