docs: api events

Author: justinmk

runtime/doc/api.txt

@@ -254,19 +254,6 @@ The idea is "versionless evolution", in the words of Rich Hickey:
 - Relaxing a requirement should be a compatible change.
 - Strengthening a promise should be a compatible change.
 
-==============================================================================
-Global events                                               *api-global-events*
-
-When a client invokes an API request as an async notification, it is not
-possible for Nvim to send an error response. Instead, in case of error, the
-following notification will be sent to the client:
-
-                                                             *nvim_error_event*
-nvim_error_event[{type}, {message}]
-
-{type} is a numeric id as defined by `api_info().error_types`, and {message} is
-a string with the error message.
-
 ==============================================================================
 Buffer update events                                    *api-buffer-updates*
 
@@ -553,6 +540,38 @@ Extmark positions changed by an edit will be restored on undo/redo. Creating
 and deleting extmarks is not a buffer change, thus new undo states are not
 created for extmark changes.
 
+==============================================================================
+Global Events                                                     *api-events*
+
+nvim_error_event({type}, {msg})                             *nvim_error_event*
+    Emitted on the client channel if an async API request responds with an
+    error.
+
+    Attributes: ~
+        |RPC| only
+
+    Parameters: ~
+      • {type}  (`integer`) Error type id as defined by
+                `api_info().error_types`.
+      • {msg}   (`string`) Error message.
+
+nvim_ui_term_event({event}, {value})                      *nvim_ui_term_event*
+    Emitted by the TUI client to signal when a host-terminal event occurred.
+
+    Supports these events:
+    • "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response
+      sequence to Nvim. The payload is the received response. Sets
+      |v:termresponse| and fires |TermResponse|.
+
+    Attributes: ~
+        |RPC| only
+        Since: 0.10.0
+
+    Parameters: ~
+      • {event}  (`string`) Event name
+      • {value}  (`any`) Event payload
+
+
 ==============================================================================
 Global Functions                                                  *api-global*
 
@@ -3660,22 +3679,6 @@ nvim_ui_set_option({name}, {value})                     *nvim_ui_set_option()*
       • {name}   (`string`)
       • {value}  (`any`)
 
-nvim_ui_term_event({event}, {value})                    *nvim_ui_term_event()*
-    Tells Nvim when a host-terminal event occurred.
-
-    Supports these events:
-    • "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response
-      sequence to Nvim. The payload is the received response. Sets
-      |v:termresponse| and fires |TermResponse|.
-
-    Attributes: ~
-        |RPC| only
-        Since: 0.10.0
-
-    Parameters: ~
-      • {event}  (`string`) Event name
-      • {value}  (`any`) Event payload
-
 nvim_ui_try_resize({width}, {height})                   *nvim_ui_try_resize()*
 
     Attributes: ~

src/gen/gen_api_dispatch.lua

@@ -395,6 +395,7 @@ output:write([[
 #include "nvim/api/buffer.h"
 #include "nvim/api/command.h"
 #include "nvim/api/deprecated.h"
+#include "nvim/api/events.h"
 #include "nvim/api/extmark.h"
 #include "nvim/api/options.h"
 #include "nvim/api/tabpage.h"

src/gen/gen_vimdoc.lua

@@ -1,5 +1,8 @@
 #!/usr/bin/env -S nvim -l
---- Generates Nvim :help docs from Lua/C docstrings
+--- Generates Nvim :help docs from Lua/C docstrings.
+---
+--- Usage:
+---     make doc
 ---
 --- The generated :help text for each function is formatted as follows:
 --- - Max width of 78 columns (`TEXT_WIDTH`).
@@ -106,6 +109,7 @@ local config = {
     filename = 'api.txt',
     section_order = {
       -- Sections at the top, in a specific order:
+      'events.c',
       'vim.c',
       'vimscript.c',
 
@@ -126,11 +130,22 @@ local config = {
       ['vim.c'] = 'Global',
     },
     section_fmt = function(name)
+      if name == 'Events' then
+        return 'Global Events'
+      end
+
       return name .. ' Functions'
     end,
     helptag_fmt = function(name)
       return fmt('api-%s', name:lower())
     end,
+    fn_helptag_fmt = function(fun)
+      local name = fun.name
+      if vim.endswith(name, '_event') then
+        return name
+      end
+      return fn_helptag_fmt_common(fun)
+    end,
   },
   lua = {
     filename = 'lua.txt',

src/nvim/api/events.c

@@ -0,0 +1,76 @@
+#include <assert.h>
+#include <inttypes.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "klib/kvec.h"
+#include "nvim/api/events.h"
+#include "nvim/api/private/converter.h"
+#include "nvim/api/private/defs.h"
+#include "nvim/api/private/helpers.h"
+#include "nvim/api/private/validate.h"
+#include "nvim/api/ui.h"
+#include "nvim/assert_defs.h"
+#include "nvim/autocmd.h"
+#include "nvim/autocmd_defs.h"
+#include "nvim/channel.h"
+#include "nvim/channel_defs.h"
+#include "nvim/eval.h"
+#include "nvim/globals.h"
+#include "nvim/main.h"
+#include "nvim/map_defs.h"
+#include "nvim/memory.h"
+#include "nvim/memory_defs.h"
+#include "nvim/msgpack_rpc/channel.h"
+#include "nvim/msgpack_rpc/channel_defs.h"
+#include "nvim/msgpack_rpc/packer.h"
+#include "nvim/msgpack_rpc/packer_defs.h"
+#include "nvim/types_defs.h"
+#include "nvim/ui.h"
+
+/// Emitted on the client channel if an async API request responds with an error.
+///
+/// @param channel_id
+/// @param type Error type id as defined by `api_info().error_types`.
+/// @param msg Error message.
+void nvim_error_event(uint64_t channel_id, Integer type, String msg)
+  FUNC_API_REMOTE_ONLY
+{
+  // TODO(bfredl): consider printing message to user, as will be relevant
+  // if we fork nvim processes as async workers
+  ELOG("async error on channel %" PRId64 ": %s", channel_id, msg.size ? msg.data : "");
+}
+
+/// Emitted by the TUI client to signal when a host-terminal event occurred.
+///
+/// Supports these events:
+///
+///   - "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response sequence to Nvim.
+///                     The payload is the received response. Sets |v:termresponse| and fires
+///                     |TermResponse|.
+///
+/// @param channel_id
+/// @param event Event name
+/// @param value Event payload
+/// @param[out] err Error details, if any.
+void nvim_ui_term_event(uint64_t channel_id, String event, Object value, Error *err)
+  FUNC_API_SINCE(12) FUNC_API_REMOTE_ONLY
+{
+  if (strequal("termresponse", event.data)) {
+    if (value.type != kObjectTypeString) {
+      api_set_error(err, kErrorTypeValidation, "termresponse must be a string");
+      return;
+    }
+
+    const String termresponse = value.data.string;
+    set_vim_var_string(VV_TERMRESPONSE, termresponse.data, (ptrdiff_t)termresponse.size);
+
+    MAXSIZE_TEMP_DICT(data, 1);
+    PUT_C(data, "sequence", value);
+    apply_autocmds_group(EVENT_TERMRESPONSE, NULL, NULL, true, AUGROUP_ALL, NULL, NULL,
+                         &DICT_OBJ(data));
+  }
+}

src/nvim/api/events.h

@@ -0,0 +1,8 @@
+#pragma once
+
+#include <stdint.h>  // IWYU pragma: keep
+
+#include "nvim/api/keysets_defs.h"  // IWYU pragma: keep
+#include "nvim/api/private/defs.h"  // IWYU pragma: keep
+
+#include "api/events.h.generated.h"

src/nvim/api/ui.c

@@ -567,37 +567,6 @@ void nvim_ui_pum_set_bounds(uint64_t channel_id, Float width, Float height, Floa
   ui->pum_pos = true;
 }
 
-/// Tells Nvim when a host-terminal event occurred.
-///
-/// Supports these events:
-///
-///   - "termresponse": The host-terminal sent a DA1, OSC, DCS, or APC response sequence to Nvim.
-///                     The payload is the received response. Sets |v:termresponse| and fires
-///                     |TermResponse|.
-///
-/// @param channel_id
-/// @param event Event name
-/// @param value Event payload
-/// @param[out] err Error details, if any.
-void nvim_ui_term_event(uint64_t channel_id, String event, Object value, Error *err)
-  FUNC_API_SINCE(12) FUNC_API_REMOTE_ONLY
-{
-  if (strequal("termresponse", event.data)) {
-    if (value.type != kObjectTypeString) {
-      api_set_error(err, kErrorTypeValidation, "termresponse must be a string");
-      return;
-    }
-
-    const String termresponse = value.data.string;
-    set_vim_var_string(VV_TERMRESPONSE, termresponse.data, (ptrdiff_t)termresponse.size);
-
-    MAXSIZE_TEMP_DICT(data, 1);
-    PUT_C(data, "sequence", value);
-    apply_autocmds_group(EVENT_TERMRESPONSE, NULL, NULL, true, AUGROUP_ALL, NULL, NULL,
-                         &DICT_OBJ(data));
-  }
-}
-
 static void flush_event(RemoteUI *ui)
 {
   if (ui->cur_event) {

src/nvim/api/vim.c

@@ -2222,15 +2222,6 @@ DictAs(eval_statusline_ret) nvim_eval_statusline(String str, Dict(eval_statuslin
   return result;
 }
 
-/// @nodoc
-void nvim_error_event(uint64_t channel_id, Integer lvl, String data)
-  FUNC_API_REMOTE_ONLY
-{
-  // TODO(bfredl): consider printing message to user, as will be relevant
-  // if we fork nvim processes as async workers
-  ELOG("async error on channel %" PRId64 ": %s", channel_id, data.size ? data.data : "");
-}
-
 /// EXPERIMENTAL: this API may change in the future.
 ///
 /// Sets info for the completion item at the given index. If the info text was shown in a window,