diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 25 |
1 files changed, 23 insertions, 2 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 2bcc996d8b..a118690876 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -9,8 +9,7 @@ Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes via |msgpack-rpc|, Lua and VimL (|eval-api|). -Nvim can also be embedded in C applications as libnvim, so the application -can control the embedded instance by calling the C API directly. +Applications can also embed libnvim to work with the C API directly. ============================================================================== API Types *api-types* @@ -55,6 +54,28 @@ error_types Possible error types returned by API functions External programs ("clients") can use the metadata to discover the |rpc-api|. ============================================================================== +API contract *api-contract* + +The API is made of functions and events. Clients call functions like those +described at |api-global|, and may "attach" in order to receive rich events, +described at |rpc-remote-ui|. + +As Nvim develops, its API may change only according the following "contract": + +- New functions and events may be added. + - Any such extensions are OPTIONAL: old clients may ignore them. +- Function signatures will NOT CHANGE (after release). + - Functions introduced in the development (unreleased) version MAY CHANGE. + (Clients can dynamically check `api_prerelease`, etc. |api-metadata|) +- Event parameters will not be removed or reordered (after release). +- Events may be EXTENDED: new parameters may be added. +- New items may be ADDED to map/list parameters/results of functions and + events. + - Any such new items are OPTIONAL: old clients may ignore them. + - Existing items will not be removed (after release). +- Deprecated functions will not be removed until Nvim version 2.0 + +============================================================================== Buffer highlighting *api-highlights* Nvim allows plugins to add position-based highlights to buffers. This is |