Merge #11500 from justinmk/api-deprecate

API: rename nvim_execute_lua, deprecate nvim_command_output

3 files changed, 34 insertions, 15 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 0d040c154b..d52a9a8409 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -479,6 +479,29 @@ created for extmark changes.
 ==============================================================================
 Global Functions                                                  *api-global*
 
+nvim_exec({src}, {output})                                       *nvim_exec()*
+                Executes Vimscript (multiline block of Ex-commands), like
+                anonymous |:source|.
+
+                Unlike |nvim_command()| this function supports heredocs,
+                script-scope (s:), etc.
+
+                On execution error: fails with VimL error, does not update
+                v:errmsg.
+
+                Parameters: ~
+                    {src}     Vimscript code
+                    {output}  Capture and return all (non-error, non-shell
+                              |:!|) output
+
+                Return: ~
+                    Output (non-error, non-shell |:!|) if `output` is true,
+                    else empty string.
+
+                See also: ~
+                    |execute()|
+                    |nvim_command()|
+
 nvim_command({command})                                       *nvim_command()*
                 Executes an ex-command.
 
@@ -488,6 +511,9 @@ nvim_command({command})                                       *nvim_command()*
                 Parameters: ~
                     {command}  Ex-command string
 
+                See also: ~
+                    |nvim_exec()|
+
 nvim_get_hl_by_name({name}, {rgb})                     *nvim_get_hl_by_name()*
                 Gets a highlight definition by name.
 
@@ -609,19 +635,9 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
                     replace_termcodes
                     cpoptions
 
-nvim_command_output({command})                         *nvim_command_output()*
-                Executes an ex-command and returns its (non-error) output.
-                Shell |:!| output is not captured.
-
-                On execution error: fails with VimL error, does not update
-                v:errmsg.
-
-                Parameters: ~
-                    {command}  Ex-command string
-
 nvim_eval({expr})                                                *nvim_eval()*
-                Evaluates a VimL expression (:help expression). Dictionaries
-                and Lists are recursively expanded.
+                Evaluates a VimL |expression|. Dictionaries and Lists are
+                recursively expanded.
 
                 On execution error: fails with VimL error, does not update
                 v:errmsg.
@@ -632,7 +648,7 @@ nvim_eval({expr})                                                *nvim_eval()*
                 Return: ~
                     Evaluation result or expanded object
 
-nvim_execute_lua({code}, {args})                          *nvim_execute_lua()*
+nvim_exec_lua({code}, {args})                                *nvim_exec_lua()*
                 Execute Lua code. Parameters (if any) are available as `...`
                 inside the chunk. The chunk can return a value.
 
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index b76a37810c..7c6b9ad1d3 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -14,6 +14,8 @@ updated.
 
 API ~
 *nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
+*nvim_command_output()*		Use |nvim_exec()| instead.
+*nvim_execute_lua()*		Use |nvim_exec_lua()| instead.
 
 Commands ~
 *:rv*
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 4c1430ab1f..09c5b7c4ad 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -236,10 +236,11 @@ with a {thing} that groups functions under a common concept).
 
 Use existing common {action} names if possible:
     add   Append to, or insert into, a collection
-    get   Get a thing (or group of things by query)
-    set   Set a thing (or group of things)
     del   Delete a thing (or group of things)
+    exec  Execute code
+    get   Get a thing (or group of things by query)
     list  Get all things
+    set   Set a thing (or group of things)
 
 Use consistent names for {thing} in all API functions. E.g. a buffer is called
 "buf" everywhere, not "buffer" in some places and "buf" in others.