docs: extmark indexing #12742

Extmarks mostly use api-indexing, except for nvim_buf_get_extmarks(),
which uses api-indexing with inclusive ranges.

ref #11456

1 files changed, 51 insertions, 10 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index dae7986fdb..18f56ba477 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -127,6 +127,10 @@ Special types (msgpack EXT) ~
 Most of the API uses 0-based indices, and ranges are end-exclusive. For the
 end of a range, -1 denotes the last line/column.
 
+Exception: the following API functions use 0-based, end-inclusive indexing:
+
+    |nvim_buf_get_extmarks()|
+
 Exception: the following API functions use "mark-like" indexing (1-based
 lines, 0-based columns):
 
@@ -443,6 +447,41 @@ in the buffer. They could be used to represent cursors, folds, misspelled
 words, and anything else that needs to track a logical location in the buffer
 over time.
 
+Extmarks use |api-indexing|, and you can think of them as cursor positions.
+For example, an extmark at position 1 exists between the first and second
+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)
+     0 1 2 3 4 5  <-- character 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
+an extmark position and enter some text, the extmark gets pushed forward. >
+
+     f o o|b a r  <-- line (| = cursor)
+          3       <-- extmark
+
+     (Now add "z" at cursor position):
+
+     f o o z|b a r  <-- line (| = cursor)
+            4       <-- extmark
+
+If your extmark is on the last possible index of a line (7 in the above
+"foozbar" example) and you enter a newline at that point, the extmark will
+accordingly be pushed to the next line: >
+
+     f o o z b a r|  <-- line (| = cursor)
+                  7  <-- extmark
+
+     (Now add <cr> at cursor position):
+
+     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
@@ -779,10 +818,9 @@ nvim_feedkeys({keys}, {mode}, {escape_csi})                  *nvim_feedkeys()*
 
                 On execution error: does not fail, but updates v:errmsg.
 
-                If you need to input sequences like <C-o> use
-                |nvim_replace_termcodes| to replace the termcodes and then
-                pass the resulting string to nvim_feedkeys. You'll also want
-                to enable escape_csi.
+                To input sequences like <C-o> use |nvim_replace_termcodes()|
+                (typically with escape_csi=true) to replace the keycodes. Then
+                pass the result to nvim_feedkeys().
 
                 Example: >
                     :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
@@ -2072,7 +2110,7 @@ nvim_buf_get_commands({buffer}, {opts})              *nvim_buf_get_commands()*
 
                                                 *nvim_buf_get_extmark_by_id()*
 nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
-                Returns position for a given extmark id
+                Gets the position (0-indexed) of an extmark {id}.
 
                 Parameters: ~
                     {buffer}  Buffer handle, or 0 for current buffer
@@ -2082,7 +2120,8 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
                               • details: Whether to include the details dict
 
                 Return: ~
-                    (row, col) tuple or empty list () if extmark id was absent
+                    0-indexed (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})
@@ -2122,10 +2161,12 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
                 Parameters: ~
                     {buffer}  Buffer handle, or 0 for current buffer
                     {ns_id}   Namespace id from |nvim_create_namespace()|
-                    {start}   Start of range, given as (row, col) or valid
-                              extmark id (whose position defines the bound)
-                    {end}     End of range, given as (row, col) or valid
-                              extmark id (whose position defines the bound)
+                    {start}   Start of range, given as 0-indexed (row, col) or
+                              valid extmark id (whose position defines the
+                              bound)
+                    {end}     End of range (inclusive), given as 0-indexed
+                              (row, col) or valid extmark id (whose position
+                              defines the bound)
                     {opts}    Optional parameters. Keys:
                               • limit: Maximum number of marks to return
                               • details Whether to include the details dict