diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 4dcf5b7bbc..c525ea7a3a 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -2290,7 +2290,16 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                               • hl_group : name of the highlight group used to
                                 highlight this mark.
                               • virt_text : virtual text to link to this mark.
-                              • virt_text_pos : positioning of virtual text.
+                                A list of [text, highlight] tuples, each
+                                representing a text chunk with specified
+                                highlight. `highlight` element can either be a
+                                a single highlight group, or an array of
+                                multiple highlight groups that will be stacked
+                                (highest priority last). A highlight group can
+                                be supplied either as a string or as an
+                                integer, the latter which can be obtained
+                                using |nvim_get_hl_id_by_name|.
+                              • virt_text_pos : position of virtual text.
                                 Possible values:
                                 • "eol": right after eol character (default)
                                 • "overlay": display over the specified
@@ -2427,44 +2436,6 @@ nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
                     {name}    Variable name
                     {value}   Variable value
 
-                                                 *nvim_buf_set_virtual_text()*
-nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks}, {opts})
-                Set the virtual text (annotation) for a buffer line.
-
-                By default (and currently the only option) the text will be
-                placed after the buffer text. Virtual text will never cause
-                reflow, rather virtual text will be truncated at the end of
-                the screen line. The virtual text will begin one cell
-                (|lcs-eol| or space) after the ordinary text.
-
-                Namespaces are used to support batch deletion/updating of
-                virtual text. To create a namespace, use
-                |nvim_create_namespace()|. Virtual text is cleared using
-                |nvim_buf_clear_namespace()|. The same `ns_id` can be used for
-                both virtual text and highlights added by
-                |nvim_buf_add_highlight()|, both can then be cleared with a
-                single call to |nvim_buf_clear_namespace()|. If the virtual
-                text never will be cleared by an API call, pass `ns_id = -1` .
-
-                As a shorthand, `ns_id = 0` can be used to create a new
-                namespace for the virtual text, the allocated id is then
-                returned.
-
-                Parameters: ~
-                    {buffer}  Buffer handle, or 0 for current buffer
-                    {ns_id}   Namespace to use or 0 to create a namespace, or
-                              -1 for a ungrouped annotation
-                    {line}    Line to annotate with virtual text
-                              (zero-indexed)
-                    {chunks}  A list of [text, hl_group] arrays, each
-                              representing a text chunk with specified
-                              highlight. `hl_group` element can be omitted for
-                              no highlight.
-                    {opts}    Optional parameters. Currently not used.
-
-                Return: ~
-                    The ns_id that was used
-
 
 ==============================================================================
 Window Functions                                                  *api-window*