api: destabilize nvim_set_hl_ns

The sematics and signature of this API is going to change, but we
don't wanna delay 0.5 for it. Mark API as unstable for now.

runtime/doc/api.txt

@@ -538,6 +538,21 @@ nvim__screenshot({path})                                  *nvim__screenshot()*
                 Attributes: ~
                     {fast}
 
+nvim__set_hl_ns({ns_id})                                   *nvim__set_hl_ns()*
+                Set active namespace for highlights.
+
+                NB: this function can be called from async contexts, but the
+                semantics are not yet well-defined. To start with
+                |nvim_set_decoration_provider| on_win and on_line callbacks
+                are explicitly allowed to change the namespace during a redraw
+                cycle.
+
+                Attributes: ~
+                    {fast}
+
+                Parameters: ~
+                    {ns_id}  the namespace to activate
+
 nvim__stats()                                                  *nvim__stats()*
                 Gets internal stats.
 
@@ -599,6 +614,22 @@ nvim_call_function({fn}, {args})                        *nvim_call_function()*
                 Return: ~
                     Result of the function call
 
+nvim_chan_send({chan}, {data})                              *nvim_chan_send()*
+                Send data to channel `id` . For a job, it writes it to the
+                stdin of the process. For the stdio channel |channel-stdio|,
+                it writes to Nvim's stdout. For an internal terminal instance
+                (|nvim_open_term()|) it writes directly to terimal output. See
+                |channel-bytes| for more information.
+
+                This function writes raw data, not RPC messages. If the
+                channel was created with `rpc=true` then the channel expects
+                RPC messages, use |vim.rpcnotify()| and |vim.rpcrequest()|
+                instead.
+
+                Parameters: ~
+                    {chan}  id of the channel
+                    {data}  data to write. 8-bit clean: can contain NUL bytes.
+
 nvim_command({command})                                       *nvim_command()*
                 Executes an ex-command.
 
@@ -1160,6 +1191,27 @@ nvim_notify({msg}, {log_level}, {opts})                        *nvim_notify()*
                     {log_level}  The log level
                     {opts}       Reserved for future use.
 
+nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
+                Open a terminal instance in a buffer
+
+                By default (and currently the only option) the terminal will
+                not be connected to an external process. Instead, input send
+                on the channel will be echoed directly by the terminal. This
+                is useful to disply ANSI terminal sequences returned as part
+                of a rpc message, or similar.
+
+                Note: to directly initiate the terminal using the right size,
+                display the buffer in a configured window before calling this.
+                For instance, for a floating display, first create an empty
+                buffer using |nvim_create_buf()|, then display it using
+                |nvim_open_win()|, and then call this function. Then
+                |nvim_chan_send()| cal be called immediately to process
+                sequences in a virtual terminal having the intended size.
+
+                Parameters: ~
+                    {buffer}  the buffer to use (expected to be empty)
+                    {opts}    Optional parameters. Reserved for future use.
+
 nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                 Open a new window.
 
@@ -1623,21 +1675,6 @@ nvim_set_hl({ns_id}, {name}, {val})                            *nvim_set_hl()*
                              keys are also recognized: `default` : don't
                              override existing definition, like `hi default`
 
-nvim_set_hl_ns({ns_id})                                     *nvim_set_hl_ns()*
-                Set active namespace for highlights.
-
-                NB: this function can be called from async contexts, but the
-                semantics are not yet well-defined. To start with
-                |nvim_set_decoration_provider| on_win and on_line callbacks
-                are explicitly allowed to change the namespace during a redraw
-                cycle.
-
-                Attributes: ~
-                    {fast}
-
-                Parameters: ~
-                    {ns_id}  the namespace to activate
-
 nvim_set_keymap({mode}, {lhs}, {rhs}, {opts})              *nvim_set_keymap()*
                 Sets a global |mapping| for the given mode.
 

src/nvim/api/vim.c

@@ -242,8 +242,7 @@ void nvim_set_hl(Integer ns_id, String name, Dictionary val, Error *err)
 ///
 /// @param ns_id the namespace to activate
 /// @param[out] err Error details, if any
-void nvim_set_hl_ns(Integer ns_id, Error *err)
-  FUNC_API_SINCE(7)
+void nvim__set_hl_ns(Integer ns_id, Error *err)
   FUNC_API_FAST
 {
   if (ns_id >= 0) {

test/functional/ui/decorations_spec.lua

@@ -179,7 +179,7 @@ describe('decorations providers', function()
                                               |
     ]]}
 
-    meths.set_hl_ns(ns1)
+    meths._set_hl_ns(ns1)
     screen:expect{grid=[[
       {10:  1 }{11:// just to see if there was an accid}|
       {10:    }{11:ent}                                 |
@@ -205,7 +205,7 @@ describe('decorations providers', function()
       local ns2 = a.nvim_create_namespace 'ns2'
       a.nvim_set_decoration_provider (ns2, {
         on_win = function (_, win, buf)
-          a.nvim_set_hl_ns(win == thewin and _G.ns1 or ns2)
+          a.nvim__set_hl_ns(win == thewin and _G.ns1 or ns2)
         end;
       })
     ]]
@@ -252,7 +252,7 @@ describe('decorations providers', function()
     ]]}
 
     meths.set_hl(ns1, 'LinkGroup', {fg = 'Blue'})
-    meths.set_hl_ns(ns1)
+    meths._set_hl_ns(ns1)
 
     screen:expect{grid=[[
       // just to see if there was an accident |
@@ -288,7 +288,7 @@ describe('decorations providers', function()
     ]]}
 
     meths.set_hl(ns1, 'LinkGroup', {fg = 'Blue', default=true})
-    meths.set_hl_ns(ns1)
+    meths._set_hl_ns(ns1)
     feed 'k'
 
     screen:expect{grid=[[