docs(autocmd): generate events enum type #34883

src/gen/cdoc_parser.lua

@@ -141,8 +141,12 @@ local function process_proto(item, state)
   cur_obj.params = cur_obj.params or {}
 
   for _, p in ipairs(item.parameters) do
-    local param = { name = p[2], type = api_type(p[1]) }
+    local event_type = 'vim.api.keyset.events|vim.api.keyset.events[]'
+    local event = (item.name == 'nvim_create_autocmd' or item.name == 'nvim_exec_autocmds')
+      and p[2] == 'event'
+    local param = { name = p[2], type = event and event_type or api_type(p[1]) }
     local added = false
+
     for _, cp in ipairs(cur_obj.params) do
       if cp.name == param.name then
         cp.type = param.type

src/gen/gen_eval_files.lua

@@ -322,12 +322,16 @@ local function get_api_keysets_meta()
 
   --- @type {name: string, keys: string[], types: table<string,string>}[]
   local keysets = metadata.keysets
+  local event_type = 'vim.api.keyset.events|vim.api.keyset.events[]'
 
   for _, k in ipairs(keysets) do
     local params = {}
     for _, key in ipairs(k.keys) do
       local pty = k.types[key] or 'any'
-      table.insert(params, { key .. '?', api_type(pty) })
+      table.insert(params, {
+        key .. '?',
+        k.name:find('autocmd') and key == 'event' and event_type or api_type(pty),
+      })
     end
     ret[k.name] = {
       signature = 'NA',
@@ -346,6 +350,16 @@ end
 local function render_api_keyset_meta(_f, fun, write)
   if string.sub(fun.name, 1, 1) == '_' then
     return -- not exported
+  elseif fun.name == 'create_autocmd' then
+    local events = vim.deepcopy(require('nvim.auevents'))
+    for event in pairs(events.aliases) do
+      events.events[event] = true
+    end
+    write('')
+    write('--- @alias vim.api.keyset.events')
+    for event in vim.spairs(events.events) do
+      write(("--- |'%s'"):format(event))
+    end
   end
   write('')
   write('--- @class vim.api.keyset.' .. fun.name)

src/nvim/api/autocmd.c

@@ -70,7 +70,8 @@ static int64_t next_autocmd_id = 1;
 /// @param opts Dict with at least one of the following:
 ///             - buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands
 ///             |autocmd-buflocal|. Cannot be used with {pattern}
-///             - event: (string|table) event or events to match against |autocmd-events|.
+///             - event: (vim.api.keyset.events|vim.api.keyset.events[])
+///               event or events to match against |autocmd-events|.
 ///             - id: (integer) Autocommand ID to match.
 ///             - group: (string|table) the autocommand group name or id to match against.
 ///             - pattern: (string|table) pattern or patterns to match against |autocmd-pattern|.
@@ -83,7 +84,7 @@ static int64_t next_autocmd_id = 1;
 ///             - callback: (function|string|nil): Lua function or name of a Vim script function
 ///               which is executed when this autocommand is triggered.
 ///             - desc: (string) the autocommand description.
-///             - event: (string) the autocommand event.
+///             - event: (vim.api.keyset.events) the autocommand event.
 ///             - id: (integer) the autocommand id (only when defined with the API).
 ///             - group: (integer) the autocommand group id.
 ///             - group_name: (string) the autocommand group name.
@@ -361,7 +362,7 @@ cleanup:
 /// pattern = vim.fn.expand('~') .. '/some/path/*.py'
 /// ```
 ///
-/// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`).
+/// @param event Event(s) that will trigger the handler (`callback` or `command`).
 /// @param opts Options dict:
 ///             - group (string|integer) optional: autocommand group name or id to match against.
 ///             - pattern (string|array) optional: pattern(s) to match literally |autocmd-pattern|.
@@ -373,7 +374,7 @@ cleanup:
 ///             value (not `false` or `nil`) to delete the autocommand, and receives one argument, a
 ///             table with these keys: [event-args]()
 ///                 - id: (number) autocommand id
-///                 - event: (string) name of the triggered event |autocmd-events|
+///                 - event: (vim.api.keyset.events) name of the triggered event |autocmd-events|
 ///                 - group: (number|nil) autocommand group id, if any
 ///                 - file: (string) [<afile>] (not expanded to a full path)
 ///                 - match: (string) [<amatch>] (expanded to a full path)
@@ -523,7 +524,7 @@ void nvim_del_autocmd(Integer id, Error *err)
 /// Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|.
 ///
 /// @param opts Parameters
-///         - event: (string|table)
+///         - event: (vim.api.keyset.events|vim.api.keyset.events[])
 ///              Examples:
 ///              - event: "pat1"
 ///              - event: { "pat1" }
@@ -674,7 +675,7 @@ void nvim_del_augroup_by_name(String name, Error *err)
 
 /// Execute all autocommands for {event} that match the corresponding
 ///  {opts} |autocmd-execute|.
-/// @param event (String|Array) The event or events to execute
+/// @param event The event or events to execute
 /// @param opts Dict of autocommand options:
 ///             - group (string|integer) optional: the autocommand group name or
 ///             id to match against. |autocmd-groups|.