api: Establish API naming convention. (#5344)

old name:                   new name:
  --------------------------------------------------
  nvim_name_to_color          nvim_get_color_by_name
  nvim_get_current_buffer     nvim_get_current_buf
  nvim_get_current_window     nvim_get_current_win
  nvim_get_buffers            nvim_list_bufs
  nvim_get_tabpages           nvim_list_tabpages
  nvim_get_windows            nvim_list_wins
  nvim_set_current_buffer     nvim_set_current_buf
  nvim_set_current_window     nvim_set_current_win
  nvim_change_directory       nvim_set_current_dir
  nvim_tabpage_get_window     nvim_tabpage_get_win
  nvim_tabpage_get_windows    nvim_tabpage_list_wins
  nvim_win_get_buffer         nvim_win_get_buf
  nvim_report_error           nvim_err_writeln

Helped-by: Björn Linse <bjorn.linse@gmail.com>
Helped-by: ZyX <kp-pav@yandex.ru>
Helped-by: James McCoy <jamessan@jamessan.com>

2 files changed, 55 insertions, 16 deletions

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 6ecbf9fb0d..ddec137079 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -124,13 +124,26 @@ include the kitchen sink... but you can use it for plumbing."
 ==============================================================================
 2. Design decisions					*design-decisions*
 
-Jargon	 							*dev-jargon*
+JARGON	 							*dev-jargon*
+
+API client ~
+All external UIs and remote plugins (as opposed to regular Vim plugins) are
+"clients" in general; but we call something an "API client" if its purpose is
+to abstract or wrap the RPC API for the convenience of other applications
+(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
+using an HTTP client like curl, but boto3 wraps that in a convenient python
+interface). For example, the Nvim lua-client is an API client:
+    https://github.com/neovim/lua-client
 
 Host ~
 A plugin "host" is both a client (of the Nvim API) and a server (of an
 external platform, e.g. python). It is a remote plugin that hosts other
 plugins.
 
+Remote plugin ~
+Arbitrary code registered via |:UpdateRemotePlugins|, that runs in a separate
+process and communicates with Nvim via the |api|.
+
 Window ~
 The word "window" is commonly used for several things: A window on the screen,
 the xterm window, a window inside Vim to view a buffer.
@@ -145,7 +158,7 @@ window		View on a buffer.  There can be several windows in Vim,
 		together with the command line, menubar, toolbar, etc. they
 		fit in the shell.
 
-Providers 							*dev-provider*
+PROVIDERS 							*dev-provider*
 
 A goal of Nvim is to allow extension of the editor without special knowledge
 in the core. But some Vim components are too tightly coupled; in those cases
@@ -189,8 +202,35 @@ Python host isn't installed then the plugin will "think" it is running in
 a Vim compiled without the |+python| feature.
 
 
-RPC API
-API client
-remote plugin
+API								*dev-api*
+
+Use this pattern to name new API functions:
+    nvim_{thing}_{action}_{arbitrary-qualifiers}
+
+If the function acts on an object then {thing} is the name of that object
+(e.g. "buf" or "win"). If the function operates in a "global" context then
+{thing} is usually omitted (but consider "namespacing" your global operations
+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 subset of things by some query)
+    set   set a thing
+    del   delete a thing (or group of things)
+    list  get all things
+
+Use consistent names for {thing} in all API function. E.g. a buffer is called
+"buf" everywhere, not "buffer" in some places and "buf" in others.
+
+Example: `nvim_get_current_line` acts on the global editor state; the common
+{action} "get" is used but {thing} is omitted.
+
+Example: `nvim_buf_add_highlight` acts on a `Buffer` object (the first
+parameter) and uses the common {action} "add".
+
+Example: `nvim_list_bufs` operates in a global context (first parameter is
+_not_ a Buffer). The common {action} "list" indicates that it lists all
+bufs (plural) in the global context.
+
 
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 59e9e44f8f..b3fed9e756 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -124,17 +124,16 @@ You can also embed an Nvim instance via |jobstart()|, and communicate using
 ==============================================================================
 4. Implementing API clients			*rpc-api-client* *api-client*
 
-All external UIs and remote plugins (as opposed to regular Vim plugins) are
-"clients" in general; but we call something an "API client" if its purpose is
-to abstract or wrap the RPC API for the convenience of other applications
-(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
-using an HTTP client like curl, but boto3 wraps that in a convenient python
-interface). For example, the lua-client is an API client:
-    https://github.com/neovim/lua-client
-
-The Python client (pip package "neovim") is the reference implementation of an
-API client. It is always up-to-date with the Nvim API, so its source code and
-test suite are an authoritative reference.
+"API clients" wrap the Nvim API to provide idiomatic "SDKs" for their
+respective platforms (see |dev-jargon|). You can build a new API client for
+your favorite platform or programming language.
+
+Existing API clients are listed here:
+    https://github.com/neovim/neovim/wiki/Related-projects#api-clients
+
+The Python client is the reference implementation for API clients. It is
+always up-to-date with the Nvim API, so its source code and test suite are
+authoritative references.
     https://github.com/neovim/python-client
 
 API client implementation guidelines ~