docs: api events

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,