diff options
| -rw-r--r-- | runtime/doc/api.txt | 37 | ||||
| -rw-r--r-- | runtime/doc/develop.txt | 30 | ||||
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 10 |
3 files changed, 35 insertions, 42 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c35c393c8b..bdeca367b1 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1,31 +1,32 @@ -*api.txt* For Nvim. {Nvim} +*api.txt* {Nvim} NVIM REFERENCE MANUAL by Thiago de Arruda -The C API of Nvim *nvim-api* -1. Introduction |nvim-api-intro| -2. API Types |nvim-api-types| -3. API metadata |nvim-api-metadata| -4. Buffer highlighting |nvim-api-highlights| +C API for Nvim *API* *api* + +1. Introduction |api-intro| +2. API Types |api-types| +3. API metadata |api-metadata| +4. Buffer highlighting |api-highlights| ============================================================================== -1. Introduction *nvim-api-intro* +1. Introduction *api-intro* -Nvim defines a C API as the primary way for external code to interact with -the Nvim core. In the present version of Nvim the API is primarily used by -external processes to interact with Nvim using the msgpack-rpc protocol, see -|msgpack-rpc|. The API will also be used from vimscript to access new Nvim core -features, but this is not implemented yet. Later on, Nvim might be embeddable -in C applications as libnvim, and the application will then control the -embedded instance by calling the C API directly. +Nvim exposes a public API for external code to interact with the Nvim core. In +the present version of Nvim the API is primarily used by external processes to +interact with Nvim using the msgpack-rpc protocol, see |msgpack-rpc|. The API +will also be used from vimscript to access new Nvim core features, but this is +not implemented yet. Later on, Nvim might be embeddable in C applications as +libnvim, and the application will then control the embedded instance by +calling the C API directly. ============================================================================== -2. API Types *nvim-api-types* +2. API Types *api-types* Nvim's C API uses custom types for all functions. Some are just typedefs -around C99 standard types, and some are Nvim defined data structures. +around C99 standard types, and some are Nvim-defined data structures. Boolean -> bool Integer (signed 64-bit integer) -> int64_t @@ -46,7 +47,7 @@ Window -> enum value kObjectTypeWindow Tabpage -> enum value kObjectTypeTabpage ============================================================================== -3. API metadata *nvim-api-metadata* +3. API metadata *api-metadata* Nvim exposes metadata about the API as a Dictionary with the following keys: @@ -58,7 +59,7 @@ This metadata is mostly useful for external programs accessing the API via RPC, see |rpc-api|. ============================================================================== -4. Buffer highlighting *nvim-api-highlights* +4. Buffer highlighting *api-highlights* Nvim allows plugins to add position-based highlights to buffers. This is similar to |matchaddpos()| but with some key differences. The added highlights diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 4912bb7ce2..658de0dce9 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -9,12 +9,12 @@ Development of Nvim. *development* 1. Design goals |design-goals| 2. Design decisions |design-decisions| -See src/nvim/README.md for a high-level overview of the source code: - https://github.com/neovim/neovim/blob/master/src/nvim/README.md - Nvim is open source software. Everybody is encouraged to contribute. https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md +See src/nvim/README.md for a high-level overview of the source code: + https://github.com/neovim/neovim/blob/master/src/nvim/README.md + ============================================================================== 1. Design goals *design-goals* @@ -72,6 +72,9 @@ NVIM IS... WELL DOCUMENTED *design-documented* recommended. - Don't make the text unnecessarily long. Less documentation means that an item is easier to find. +- Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document + differences from Vim. The {Nvim} annotation is also available + to mark a specific feature. No other distinction is necessary. NVIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size* @@ -85,8 +88,6 @@ fast. possible. Useful commands may take longer. - Don't forget that some people use Vim over a slow connection. Minimize the communication overhead. -- Items that add considerably to the size and are not used by many people - should be a feature that can be disabled. - Vim is a component among other components. Don't turn it into a massive application, but have it work well together with other programs. @@ -113,25 +114,14 @@ be used to adjust Vim to the desire of the user and its environment. NVIM IS... NOT *design-not* -Nvim is not an operating system—instead it should be composed with other tools -or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not +Nvim is not an operating system; instead it should be composed with other +tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not include the kitchen sink... but you can use it for plumbing." ============================================================================== 2. Design decisions *design-decisions* -Folding - -Several forms of folding should be possible for the same buffer. For example, -have one window that shows the text with function bodies folded, another -window that shows a function body. - -Folding is a way to display the text. It should not change the text itself. -Therefore the folding has been implemented as a filter between the text stored -in a buffer (buffer lines) and the text displayed in a window (logical lines). - - Naming the window The word "window" is commonly used for several things: A window on the screen, @@ -147,6 +137,8 @@ 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. - +RPC API +API client +remote plugin vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 52d2efd8da..2db7c498e3 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -35,10 +35,10 @@ The RPC API is like a more powerful version of Vim's `clientserver` feature. ============================================================================== 2. API mapping *rpc-api* -The Nvim C API, see |nvim-api|, is automatically exposed to the RPC API by the -build system, which parses headers at src/nvim/api/*. A dispatch function is -generated which matches RPC API method names with public API functions, -converting/validating arguments and return values back to msgpack. +The Nvim C |API| is automatically exposed to the RPC API by the build system, +which parses headers at src/nvim/api/*. A dispatch function is generated which +matches RPC API method names with public API functions, converting/validating +arguments and return values back to msgpack. Client libraries (|api-client|s) normally provide wrappers that hide msgpack-rpc details from application developers. The wrappers can be @@ -184,7 +184,7 @@ Vim class with methods mapped to functions prefixed with `vim_`. ============================================================================== 5. Types *rpc-types* -The Nvim C API uses custom types for all functions. |nvim-api-types| +The Nvim C API uses custom types for all functions. |api-types| For the purpose of mapping to msgpack, the types can be split into two groups: - Basic types that map natively to msgpack (and probably have a default |