docs: extmarks indexing #15311

fix #11456

2 files changed, 35 insertions, 15 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 18f56ba477..6247aab550 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -127,10 +127,6 @@ 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):
 
@@ -138,6 +134,14 @@ lines, 0-based columns):
     |nvim_win_get_cursor()|
     |nvim_win_set_cursor()|
 
+Exception: the following API functions use |extmarks| indexing (0-based lines,
+0-based columns end-inclusive):
+
+    |nvim_buf_del_extmark()|
+    |nvim_buf_get_extmark_by_id()|
+    |nvim_buf_get_extmarks()|
+    |nvim_buf_set_extmark()|
+
 							*api-fast*
 Most API functions are "deferred": they are queued on the main loop and
 processed sequentially with normal input.  So if the editor is waiting for
@@ -440,12 +444,13 @@ Example: create a float with scratch buffer: >
 >
 
 ==============================================================================
-Extended marks						   *api-extended-marks*
+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
 words, and anything else that needs to track a logical location in the buffer
-over time.
+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.
 For example, an extmark at position 1 exists between the first and second
@@ -488,12 +493,16 @@ We will set an extmark at the first row and third column. |api-indexing| is
 zero-indexed, so we use row=0 and column=2. Passing id=0 creates a new mark
 and returns the id: >
 
+      01 2345678
+    0 ex|ample..
+<        ^ This is the extmark position
+>
     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, 2, {})
+<
 We can get a mark 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]
 
 We can get all marks in a buffer for our namespace (or by a range): >
@@ -502,7 +511,18 @@ We can get all marks in a buffer for our namespace (or by a range): >
     => [[1, 0, 2]]
 
 Deleting all text surrounding an extmark does not remove the extmark. To
-remove an extmark use |nvim_buf_del_extmark()|.
+remove an extmark 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
+>
+    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
+    text edit. See |nvim_buf_set_extmark()| for more information.
 
 Namespaces allow your plugin to manage only its own extmarks, ignoring those
 created by another plugin.
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 3260c083b8..3808f601d9 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -1232,7 +1232,7 @@ static Array extmark_to_array(ExtmarkInfo extmark, bool id, bool add_dict)
   return rv;
 }
 
-/// Gets the position (0-indexed) of an extmark {id}.
+/// Gets the position (0-indexed) of an extmark.
 ///
 /// @param buffer  Buffer handle, or 0 for current buffer
 /// @param ns_id  Namespace id from |nvim_create_namespace()|
@@ -1321,10 +1321,10 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
 ///
 /// @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 0-indexed (row, col) or valid
-///               extmark id (whose position defines the bound)
-/// @param end  End of range (inclusive), given as 0-indexed (row, col) or
-///             valid extmark id (whose position defines the bound)
+/// @param start  Start of range: a 0-indexed (row, col) or valid extmark id
+/// (whose position defines the bound). |api-indexing|
+/// @param end  End of range (inclusive): a 0-indexed (row, col) or valid
+/// extmark id (whose position defines the bound). |api-indexing|
 /// @param opts  Optional parameters. Keys:
 ///          - limit:  Maximum number of marks to return
 ///          - details Whether to include the details dict