diff options
| -rw-r--r-- | runtime/doc/api.txt | 47 | ||||
| -rw-r--r-- | runtime/doc/deprecated.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 48 | ||||
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 11 | ||||
| -rw-r--r-- | runtime/doc/starting.txt | 81 | ||||
| -rw-r--r-- | runtime/doc/ui.txt | 95 | ||||
| -rwxr-xr-x | scripts/gen_vimdoc.py | 10 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 10 | ||||
| -rw-r--r-- | src/nvim/api/ui.c | 21 |
9 files changed, 180 insertions, 146 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c8b9dd5fad..b2e37a6d60 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -206,17 +206,15 @@ Highlights are registered using the |nvim_buf_add_highlight()| function. If an external highlighter plugin wants to add many highlights in a batch, performance can be improved by calling |nvim_buf_add_highlight()| as an asynchronous notification, after first (synchronously) reqesting a source id. -Example using the Nvim python-client: + +Example using the Python API client (|pynvim|): > src = vim.new_highlight_source() - buf = vim.current.buffer for i in range(5): buf.add_highlight("String",i,0,-1,src_id=src) - - # some time later - - buf.clear_highlight(src) + # some time later ... + buf.clear_namespace(src) < If the highlights don't need to be deleted or updated, just pass -1 as src_id (this is the default in python). Use |nvim_buf_clear_namespace()| to @@ -224,13 +222,12 @@ clear highlights from a specific source, in a specific line range or the entire buffer by passing in the line range 0, -1 (the latter is the default in python as used above). -An example of calling the api from vimscript: > +Example using the API from Vimscript: > call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"]) let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4) call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1) - - " later + " some time later ... call nvim_buf_clear_namespace(0, src, 0, -1) @@ -494,8 +491,6 @@ nvim_set_current_dir({dir}) *nvim_set_current_dir()* nvim_get_current_line() *nvim_get_current_line()* Gets the current line. - Parameters: ~ - Return: ~ Current line string @@ -508,8 +503,6 @@ nvim_set_current_line({line}) *nvim_set_current_line()* nvim_del_current_line() *nvim_del_current_line()* Deletes the current line. - Parameters: ~ - nvim_get_var({name}) *nvim_get_var()* Gets a global (g:) variable. @@ -656,6 +649,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* For a general overview of floats, see |api-floatwin|. Exactly one of `external` and `relative` must be specified. + The `width` and `height` of the new window must be specified. With editor positioning row=0, col=0 refers to the top-left corner of the screen-grid and row=Lines-1, Columns-1 refers to @@ -697,7 +691,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* - `height` : window height (in character cells). Minimum of 1. - `width` : window width (in character cells). - Minimum of 2. + Minimum of 1. - `row` : row position. Screen cell height are used as unit. Can be floating point. - `col` : column position. Screen cell width is @@ -1161,7 +1155,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* - Activate updates from this buffer to the current channel. + Activates buffer-update events on the channel. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -1180,7 +1174,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* True. nvim_buf_detach({buffer}) *nvim_buf_detach()* - Deactivate updates from this buffer to the current channel. + Deactivates buffer-update events on the channel. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -1738,10 +1732,27 @@ nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* UI Functions *api-ui* nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* - TODO: Documentation + Activates UI events on the channel. + + Entry point of all UI clients. Allows |--embed| to continue + startup. Implies that the client is ready to show the UI. Adds + the client to the list of UIs. |nvim_list_uis()| + + Note: + If multiple UI clients are attached, the global screen + dimensions degrade to the smallest client. E.g. if client + A requests 80x40 but client B requests 200x100, the global + screen has size 80x40. + + Parameters: ~ + {width} Requested screen columns + {height} Requested screen rows + {options} |ui-options| map nvim_ui_detach() *nvim_ui_detach()* - TODO: Documentation + Deactivates UI events on the channel. + + Removes the client from the list of UIs. |nvim_list_uis()| nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* TODO: Documentation diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 9e74efabe0..9272c0693e 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -12,6 +12,9 @@ updated. ============================================================================== +API ~ +*nvim_buf_clear_highlight()* Use |nvim_buf_clear_namespace()| instead. + Commands ~ *:rv* *:rviminfo* Deprecated alias to |:rshada| command. diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index d400df6b7d..9e2994ae2e 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1502,7 +1502,8 @@ v:dying Normally zero. When a deadly signal is caught it's set to v:exiting Exit code, or |v:null| if not exiting. |VimLeave| *v:errmsg* *errmsg-variable* -v:errmsg Last given error message. It's allowed to set this variable. +v:errmsg Last given error message. + Modifiable (can be set). Example: > :let v:errmsg = "" :silent! next @@ -1827,7 +1828,8 @@ v:shell_error Result of the last shell command. When non-zero, the last :endif < *v:statusmsg* *statusmsg-variable* -v:statusmsg Last given status message. It's allowed to set this variable. +v:statusmsg Last given status message. + Modifiable (can be set). *v:stderr* *stderr-variable* v:stderr |channel-id| corresponding to stderr. The value is always 2; @@ -1893,9 +1895,9 @@ v:termresponse The escape sequence returned by the terminal for the DA v:testing Must be set before using `test_garbagecollect_now()`. *v:this_session* *this_session-variable* -v:this_session Full filename of the last loaded or saved session file. See - |:mksession|. It is allowed to set this variable. When no - session file has been saved, this variable is empty. +v:this_session Full filename of the last loaded or saved session file. + Empty when no session file has been saved. See |:mksession|. + Modifiable (can be set). *v:throwpoint* *throwpoint-variable* v:throwpoint The point where the exception most recently caught and not @@ -1922,22 +1924,20 @@ v:val Value of the current item of a |List| or |Dictionary|. Only |filter()|. Read-only. *v:version* *version-variable* -v:version Version number of Vim: Major version number times 100 plus - minor version number. Version 5.0 is 500. Version 5.1 (5.01) - is 501. Read-only. "version" also works, for backwards - compatibility. - Use |has()| to check if a certain patch was included, e.g.: > - if has("patch-7.4.123") -< Note that patch numbers are specific to the version, thus both - version 5.0 and 5.1 may have a patch 123, but these are - completely different. +v:version Vim version number: major version times 100 plus minor + version. Vim 5.0 is 500, Vim 5.1 is 501. + Read-only. + Use |has()| to check the Nvim (not Vim) version: > + :if has("nvim-0.2.1") +< *v:vim_did_enter* *vim_did_enter-variable* -v:vim_did_enter Zero until most of startup is done. It is set to one just - before |VimEnter| autocommands are triggered. +v:vim_did_enter 0 during startup, 1 just before |VimEnter|. + Read-only. *v:warningmsg* *warningmsg-variable* -v:warningmsg Last given warning message. It's allowed to set this variable. +v:warningmsg Last given warning message. + Modifiable (can be set). *v:windowid* *windowid-variable* v:windowid Application-specific window "handle" which may be set by any @@ -4674,8 +4674,8 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The {feature} argument is a feature name like "nvim-0.2.1" or "win32", see below. See also |exists()|. - Vim's compile-time feature names (prefixed with "+") are not - supported because Nvim is always compiled with ALL possible + Vim's compile-time feature-names (prefixed with "+") are not + recognized because Nvim is always compiled with all possible features. |feature-compile| Feature names can be: @@ -4704,14 +4704,12 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The wsl WSL (Windows Subsystem for Linux) system *has-patch* - 3. Vim patches. The "patch123" feature means that Vim patch - 123 has been included. This does not check the Vim - version, you could check |v:version| for that. - Example: > + 3. Vim patch. For example the "patch123" feature means that + Vim patch 123 at the current |v:version| was included: > :if v:version > 602 || v:version == 602 && has("patch148") -< 5. Vim version. For example the "patch-7.4.237" feature means - that the Vim version is 7.4.237 or later. > +< 4. Vim version. For example the "patch-7.4.237" feature means + that Nvim is Vim-compatible to version 7.4.237 or later. > :if has("patch-7.4.237") diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 862aa7b750..91a4a3c267 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -114,17 +114,18 @@ You can also embed an Nvim instance via |jobstart()|, and communicate using ============================================================================== 4. Implementing API clients *rpc-api-client* *api-client* -"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. +API clients wrap the Nvim API to provide idiomatic "SDKs" for their respective +platforms (see |jargon|). You can build a new API client for your favorite +platform or programming language. -Existing API clients are listed here: +API clients are listed here: https://github.com/neovim/neovim/wiki/Related-projects#api-clients + *pynvim* 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 + https://github.com/neovim/pynvim API client implementation guidelines ~ diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index a8ba64fda8..771165c361 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -195,34 +195,33 @@ argument. -E Start Nvim in Ex mode |gQ|. If stdin is not a TTY: - -e reads stdin as Ex commands. + -e reads/executes stdin as Ex commands. -E reads stdin as text (into buffer 1). - *-es* *-Es* --es *-s-ex* *silent-mode* --Es Silent or batch mode: execute Ex commands from a file instead - of a terminal. Special case of |-s| (which takes an argument - while "-es" doesn't). Disables most prompts, messages, - warnings and errors. - Output of these commands is displayed (to stdout): +-es *-es* *-Es* *-s-ex* *silent-mode* +-Es Silent or batch mode. Special case of |-s| (which takes an + argument while "-es" doesn't). Disables most prompts, + messages, warnings and errors. + + -es reads/executes stdin as Ex commands. > + printf "put ='foo'\n%%print\n" | nvim -es + +< -Es reads stdin as text (into buffer 1). Use |-c| or "+" to + send commands. > + printf "foo\n" | nvim -Es +"%print" + +< Output of these commands is displayed (to stdout): :print :list :number - :set to display option values. - When 'verbose' is set messages are printed to stderr, e.g.: > + :set (to display option values) + When 'verbose' is set messages are printed to stderr. > echo foo | nvim -V1 -es -< - User |init.vim| is skipped (unless given with |-u|). - Swap file is skipped (like |-n|). - |$TERM| is not used. - If stdin is not a TTY: - -es reads stdin as Ex commands. - -Es reads stdin as text (into buffer 1). +< User |init.vim| is skipped (unless given with |-u|). + Swap file is skipped (like |-n|). + User |shada| is loaded (unless "-i NONE" is given). - Example: > - printf "put ='foo'\n%%print\n" | nvim -es -< *-b* -b Binary mode. File I/O will only recognize <NL> to separate lines. The 'expandtab' option will be reset. The 'textwidth' @@ -355,35 +354,33 @@ argument. --embed Use stdin/stdout as a msgpack-RPC channel, so applications can embed and control Nvim via the |rpc-api|. - By default nvim will wait for the embedding process to call - `nvim_ui_attach` before sourcing startup files and reading - buffers. This is so that UI can show startup messages and - possible swap file dialog for the first loaded file. The - process can do requests before the `nvim_ui_attach`, for - instance a `nvim_get_api_info` call so that UI features can be - safely detected by the UI before attaching. - - See |ui-startup| for more information about UI startup. - - To embed nvim without using the UI protocol, `--headless` should - be supplied together with `--embed`. Then initialization is - performed without waiting for an UI. This is also equivalent - to the following alternative: > - nvim --headless --cmd "call stdioopen({'rpc': v:true})" -< - See also |channel-stdio|. + Waits for the client ("embedder") to call |nvim_ui_attach()| + before sourcing startup files and reading buffers, so that UIs + can deterministically handle (display) early messages, + dialogs, etc. The client can do other requests before + `nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection). + During this pre-startup phase the user config is of course not + available (similar to `--cmd`). + + Embedders _not_ using the UI protocol must pass |--headless|: > + nvim --embed --headless + +< Then startup will continue without waiting for `nvim_ui_attach`. + This is equivalent to: > + nvim --headless --cmd "call stdioopen({'rpc': v:true})" + +< See also: |ui-startup| |channel-stdio| *--headless* ---headless Start nvim without an UI. The TUI is not used, so stdio - can be used as an arbitrary communication channel. - |channel-stdio| When used together with `--embed`, do not wait - for the embedder to attach an UI. +--headless Start without UI, and do not wait for `nvim_ui_attach`. The + builtin TUI is not used, so stdio works as an arbitrary + communication channel. |channel-stdio| Also useful for scripting (tests) to see messages that would not be printed by |-es|. To detect if a UI is available, check if |nvim_list_uis()| is - empty in or after |VimEnter|. + empty during or after |VimEnter|. To read stdin as text, "-" must be given explicitly: --headless cannot assume that stdin is just text. > diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 98476ea8fa..73eb2210f5 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -64,7 +64,7 @@ the batch array, nor after a batch not ending with "flush". By default, Nvim sends |ui-global| and |ui-grid-old| events; these suffice to implement a terminal-like interface. However there are two revisions of the grid part of the protocol. The newer revision |ui-linegrid|, enabled by -`ext_linegrid` option, has a more effecient representation of text (especially +`ext_linegrid` option, has a more efficient representation of text (especially highlighted text), and allows extensions that use multiple grids. The older revision is available and used by default only for backwards @@ -83,35 +83,31 @@ for forward-compatibility. |api-contract| ============================================================================== UI startup *ui-startup* -Nvim defines a standard procedure for how an embedding UI should interact with -the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag -but not the |--headless| flag. The started Nvim process will pause before loading -startup files and reading buffers, and give the UI a chance to invoke requests -to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the -startup will continue. +UI embedders (clients that start Nvim with |--embed| and later call +|nvim_ui_attach()|) must start Nvim without |--headless|: > + nvim --embed +Nvim will pause before loading startup files and reading buffers, so the UI +has a chance to invoke requests and do early initialization. Startup will +continue as soon as the UI invokes |nvim_ui_attach()|. -A simple UI only need to do a single |nvim_ui_attach()| request and then -be prepared to handle any UI event. A more featureful UI, which might need +A simple UI only needs to do a single |nvim_ui_attach()| request and then +prepare to handle any UI event. A more featureful UI, which might need additional configuration of the nvim process, should use the following startup procedure: -1. Invoke |nvim_get_api_info()|, if this is needed to setup the client library - and/or to get the list of supported UI extensions. -2. At this time, any configuration that should be happen before init.vim - loading should be done. Buffers and windows are not available at this - point, but this could be used to set |g:| variables visible to init.vim -3. If the UI wants to do additional setup after the init.vim file was loaded - register an autocmd for VimEnter at this point: > - - nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')") - -<4. Now invoke |nvim_ui_attach()|. The UI will need to handle keyboard input - at this point, as sourcing init.vim and loading buffers might lead to - blocking prompts. -5. If step 3 was used, nvim will send a blocking "vimenter" request to the - UI. Inside this request handler, the UI can safely do any initialization - before entering normal mode, for instance reading variables set by - init.vim. +1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or + to get the list of supported UI extensions. +2. Do any configuration that should be happen before user config is loaded. + Buffers and windows are not available at this point, but this could be used + to set |g:| variables visible to init.vim +3. If the UI wants to do additional setup after user config is loaded, + register a VimEnter autocmd: > + nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')") +<4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now: + sourcing init.vim and loading buffers might lead to blocking prompts. +5. If step 3 was used, Nvim will send a blocking "vimenter" request to the UI. + Inside this request handler, the UI can safely do any initialization before + entering normal mode, for example reading variables set by init.vim. ============================================================================== Global Events *ui-global* @@ -220,7 +216,7 @@ Grid Events (line-based) *ui-linegrid* These events are used if `ext_linegrid` option is set (recommended for all new UIs). The biggest change compared to previous revision is to use a single -event `grid_line` to update the contents of a screen line (where the old +`grid_line` event to update the contents of a screen line (where the old protocol used a combination of cursor, highlight and text events) Most of these events take a `grid` index as first parameter. Grid 1 is the @@ -231,7 +227,7 @@ created. To enable per-window grids, `ext_multigrid` option should be set (see |ui-multigrid|). Highlight attribute groups are predefined. UIs should maintain a table to map -numerical highlight `id`:s to the actual attributes. +numerical highlight ids to the actual attributes. ["grid_resize", grid, width, height] Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is @@ -242,12 +238,12 @@ numerical highlight `id`:s to the actual attributes. special colors respectively. `cterm_fg` and `cterm_bg` specifies the default color codes to use in a 256-color terminal. - The rgb values will always be valid colors, by default. If no + The RGB values will always be valid colors, by default. If no colors have been set, they will default to black and white, depending on 'background'. By setting the `ext_termcolors` option, instead - -1 will be used for unset colors. This is mostly useful for a - TUI implementation, where using the terminal emulators builitn - defaults are expected. + -1 will be used for unset colors. This is mostly useful for a TUI + implementation, where using the terminal builtin ("ANSI") defaults + are expected. Note: unlike the corresponding events in the first revision, the screen is not always cleared after sending this event. The GUI has to @@ -275,7 +271,7 @@ numerical highlight `id`:s to the actual attributes. All boolean keys default to false, and will only be sent when they are true. - Highlights are always transmitted both for both the rgb format and as + Highlights are always transmitted both for both the RGB format and as terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters respectively. The |ui-rgb| option has no effect effect anymore. Most external UIs will only need to store and use the `rgb_attr` @@ -284,17 +280,17 @@ numerical highlight `id`:s to the actual attributes. `id` 0 will always be used for the default highlight with colors defined by `default_colors_set` and no styles applied. - Note: `id`:s can be reused if Nvim's internal highlight table is full. - In this case, Nvim will always issue redraws of screen cells that are - affected by redefined `id`:s, so UIs do not need to keep track of this + Note: Nvim may reuse `id` values if its internal highlight table is full. + In that case Nvim will always issue redraws of screen cells that are + affected by redefined ids, so UIs do not need to keep track of this themselves. - `info` is an empty array per default, and will be used by the - |ui-hlstate| extension explaned below. + `info` is an empty array by default, and will be used by the + |ui-hlstate| extension explained below. *ui-event-grid_line* ["grid_line", grid, row, col_start, cells] - Redraw a continous part of a `row` on a `grid`, starting at the column + Redraw a continuous part of a `row` on a `grid`, starting at the column `col_start`. `cells` is an array of arrays each with 1 to 3 items: `[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in a cell, with the highlight `hl_id` defined by a previous `hl_attr_define` @@ -407,7 +403,7 @@ option is not set. New UIs should use |ui-linegrid|. updates. All boolean keys default to false. `foreground`: foreground color. - `background`: backround color. + `background`: background color. `special`: color to use for underline and undercurl, when present. `reverse`: reverse video. Foreground and background colors are switched. @@ -465,10 +461,10 @@ Detailed highlight state Extension *ui-hlstate* Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies `ext_linegrid`. -By default, nvim will only describe grid cells using the final calculated -higlight attributes, as described by the dict keys in |ui-event-highlight_set|. +By default Nvim will only describe grid cells using the final calculated +highlight attributes, as described by the dict keys in |ui-event-highlight_set|. The `ext_hlstate` extension allows to the UI to also receive a semantic -describtion of the higlights active in a cell. In this mode highlights will be +description of the highlights active in a cell. In this mode highlights will be predefined in a table, see |ui-event-hl_attr_define| and |ui-event-grid_line|. The `info` parameter in `hl_attr_define` will contain a semantic description of the highlights. As highlight groups can be combined, this will be an array @@ -476,14 +472,13 @@ of items, with the item with highest priority last. Each item is a dictionary with the following possible keys: `kind`: always present. One of the following values: - "ui": A builtin ui highlight. - "syntax": highlight applied to a buffer by a syntax declaration or - other runtime/plugin functionallity such as + "ui": Builtin UI highlight. |highlight-groups| + "syntax": Highlight applied to a buffer by a syntax declaration or + other runtime/plugin functionality such as |nvim_buf_add_highlight()| "terminal": highlight from a process running in a |terminal-emulator|. - Contains no futher semantic information. - `ui_name`: Name of the builtin highlight. See |highlight-groups| for - possible values. Only present for "ui". + Contains no further semantic information. + `ui_name`: Highlight name from |highlight-groups|. Only for "ui" kind. `hi_name`: Name of the final |:highlight| group where the used attributes are defined. `id`: Unique numeric id representing this item. @@ -532,7 +527,7 @@ tabs. ["win_external_pos", grid, win] Display or reconfigure external window `win`. The window should be - displayed as a separate top-level window in the desktop envirionment, + displayed as a separate top-level window in the desktop environment, or something similar. ["win_hide", grid] diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py index a62d18f02e..3449cf68e5 100755 --- a/scripts/gen_vimdoc.py +++ b/scripts/gen_vimdoc.py @@ -219,6 +219,14 @@ def doc_wrap(text, prefix='', width=70, func=False, indent=None): return result +def has_nonexcluded_params(nodes): + """Returns true if any of the given <parameterlist> elements has at least + one non-excluded item.""" + for n in nodes: + if render_params(n) != '': + return True + + def render_params(parent, width=62): """Renders Doxygen <parameterlist> tag as Vim help text.""" name_length = 0 @@ -356,7 +364,7 @@ def render_para(parent, indent='', width=62): chunks = [text] # Generate text from the gathered items. - if len(groups['params']) > 0: + if len(groups['params']) > 0 and has_nonexcluded_params(groups['params']): chunks.append('\nParameters: ~') for child in groups['params']: chunks.append(render_params(child, width=width)) diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index e27c85cd4f..da4db60ad6 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -97,7 +97,7 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err) return rv; } -/// Activate updates from this buffer to the current channel. +/// Activates buffer-update events on the channel. /// /// @param channel_id /// @param buffer Buffer handle, or 0 for current buffer @@ -106,7 +106,7 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err) /// `nvim_buf_lines_event`. Otherwise, the first notification will be /// a `nvim_buf_changedtick_event` /// @param opts Optional parameters. Reserved for future use. -/// @param[out] err Details of an error that may have occurred +/// @param[out] err Error details, if any /// @return False when updates couldn't be enabled because the buffer isn't /// loaded or `opts` contained an invalid key; otherwise True. Boolean nvim_buf_attach(uint64_t channel_id, @@ -129,12 +129,12 @@ Boolean nvim_buf_attach(uint64_t channel_id, return buf_updates_register(buf, channel_id, send_buffer); } -// -/// Deactivate updates from this buffer to the current channel. + +/// Deactivates buffer-update events on the channel. /// /// @param channel_id /// @param buffer Buffer handle, or 0 for current buffer -/// @param[out] err Details of an error that may have occurred +/// @param[out] err Error details, if any /// @return False when updates couldn't be disabled because the buffer /// isn't loaded; otherwise True. Boolean nvim_buf_detach(uint64_t channel_id, diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c index d50a91f261..fd94418d48 100644 --- a/src/nvim/api/ui.c +++ b/src/nvim/api/ui.c @@ -76,6 +76,21 @@ void remote_ui_wait_for_attach(void) pmap_has(uint64_t)(connected_uis, CHAN_STDIO)); } +/// Activates UI events on the channel. +/// +/// Entry point of all UI clients. Allows |\-\-embed| to continue startup. +/// Implies that the client is ready to show the UI. Adds the client to the +/// list of UIs. |nvim_list_uis()| +/// +/// @note If multiple UI clients are attached, the global screen dimensions +/// degrade to the smallest client. E.g. if client A requests 80x40 but +/// client B requests 200x100, the global screen has size 80x40. +/// +/// @param channel_id +/// @param width Requested screen columns +/// @param height Requested screen rows +/// @param options |ui-options| map +/// @param[out] err Error details, if any void nvim_ui_attach(uint64_t channel_id, Integer width, Integer height, Dictionary options, Error *err) FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY @@ -164,6 +179,12 @@ void ui_attach(uint64_t channel_id, Integer width, Integer height, api_free_dictionary(opts); } +/// Deactivates UI events on the channel. +/// +/// Removes the client from the list of UIs. |nvim_list_uis()| +/// +/// @param channel_id +/// @param[out] err Error details, if any void nvim_ui_detach(uint64_t channel_id, Error *err) FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY { |