Merge #15311 docs(extmarks)

2 files changed, 13 insertions, 12 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 878ffdf06f..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;
 }
 
-/// Returns position for a given 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()|
@@ -1240,7 +1240,8 @@ static Array extmark_to_array(ExtmarkInfo extmark, bool id, bool add_dict)
 /// @param opts  Optional parameters. Keys:
 ///          - details: Whether to include the details dict
 /// @param[out] err   Error details, if any
-/// @return (row, col) tuple or empty list () if extmark id was absent
+/// @return 0-indexed (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, Dictionary opts,
                                             Error *err)
@@ -1320,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 (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 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
@@ -1424,8 +1425,8 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id,
 ///
 /// @param buffer  Buffer handle, or 0 for current buffer
 /// @param ns_id  Namespace id from |nvim_create_namespace()|
-/// @param line  Line where to place the mark, 0-based
-/// @param col  Column where to place the mark, 0-based
+/// @param line  Line where to place the mark, 0-based. |api-indexing|
+/// @param col  Column where to place the mark, 0-based. |api-indexing|
 /// @param opts  Optional parameters.
 ///               - id : id of the extmark to edit.
 ///               - end_line : ending line of the mark, 0-based inclusive.
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 5f48a26a29..f65d5cc185 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -275,9 +275,9 @@ static void on_redraw_event(void **argv)
 ///
 /// 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 |keycodes|, then pass the result to
+/// nvim_feedkeys().
 ///
 /// Example:
 /// <pre>
@@ -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()|.