doc: improve lua language server typing annotations

lua/astrocore/config.lua

@@ -7,6 +7,18 @@
 -- copyright 2023
 -- GNU General Public License v3.0
 
+---@class AstroCoreMapping: vim.api.keyset.keymap
+---@field [1] string|function rhs of keymap
+---@field name string? optional which-key mapping name
+
+---@alias AstroCoreMappings table<string,table<string,(AstroCoreMapping|string|false)?>?>
+
+---@class AstroCoreCommand: vim.api.keyset.user_command
+---@field [1] string|function the command to execute
+
+---@class AstroCoreAutocmd: vim.api.keyset.create_autocmd
+---@field event string|string[] Event(s) that will trigger the handler
+
 ---@class AstroCoreGitWorktree
 ---@field toplevel string the top level directory
 ---@field gitdir string the location of the git directory
@@ -85,7 +97,7 @@
 ---  }
 ---}
 ---```
----@field autocmds table<string,table[]|false>?
+---@field autocmds table<string,AstroCoreAutocmd[]|false>?
 ---Configuration of user commands
 ---The key into the table is the name of the user command and the value is a table of command options
 ---Example:
@@ -101,7 +113,7 @@
 ---  }
 ---}
 ---```
----@field commands table<string,table|false>?
+---@field commands table<string,AstroCoreCommand|false>?
 ---Configuration of vim mappings to create.
 ---The first key into the table is the vim map mode (`:h map-modes`), and the value is a table of entries to be passed to `vim.keymap.set` (`:h vim.keymap.set`):
 ---  - The key is the first parameter or the vim mode (only a single mode supported) and the value is a table of keymaps within that mode:
@@ -133,7 +145,7 @@
 ---  }
 ---}
 ---```
----@field mappings table<string,table<string,(table|string|false)?>?>?
+---@field mappings AstroCoreMappings?
 ---@field _map_sections table<string,{ desc: string?, name: string? }>?
 ---Configuration of vim `on_key` functions.
 ---The key into the table is the namespace of the function and the value is a list like table of `on_key` functions

lua/astrocore/init.lua

@@ -239,8 +239,8 @@ function M.empty_map_table()
 end
 
 --- Table based API for setting keybindings
----@param map_table table A nested table where the first key is the vim mode, the second key is the key to map, and the value is the function to set the mapping to
----@param base? table A base set of options to set on every keybinding
+---@param map_table AstroCoreMappings A nested table where the first key is the vim mode, the second key is the key to map, and the value is the function to set the mapping to
+---@param base? vim.api.keyset.keymap A base set of options to set on every keybinding
 function M.set_mappings(map_table, base)
   local was_no_which_key_queue = not M.which_key_queue
   -- iterate over the first keys for each mode
@@ -250,9 +250,11 @@ function M.set_mappings(map_table, base)
     for keymap, options in pairs(maps) do
       -- build the options for the command accordingly
       if options then
-        local cmd = options
+        local cmd
         local keymap_opts = base
-        if type(options) == "table" then
+        if type(options) == "string" then
+          cmd = options
+        else
           cmd = options[1]
           keymap_opts = vim.tbl_deep_extend("force", keymap_opts, options)
           keymap_opts[1] = nil