Enhance documentation for calendar event functions by refining return types and parameter aliases

api/CalculateAuctionDeposit.lua

@@ -1,10 +1,12 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param runTime 2880 
----@param 720  
----@param 1440  
----@param 2880  
+---@alias auctionRunTime
+---| 720
+---| 1440
+---| 2880
+
+---@param runTime auctionRunTime
 ---@return number deposit
 ---Returns the deposit amount for the item currently being set up for auction. Only returns useful information once an item has been placed in the Create Auction UI's "auction item" slot (see ClickAuctionSellItemButton()).  Deposit amount for an auction varies based on the item being auction, the auction's proposed run time, and the auction house being used (i.e. faction or neutral).
-function CalculateAuctionDeposit(runTime, 720, 1440, 2880) end
+function CalculateAuctionDeposit(runTime) end

api/CalendarContextDeselectEvent.lua

@@ -1,5 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----Clears the event selection used only for CalendarContext functions. The selection state cleared by this function is used only by other CalendarContext functions; other calendar event functions use the selection state set by CalendarOpenEvent, CalendarNewEvent, CalendarNewGuildEvent, or CalendarNewGuildAnnouncement (if they use a selection state at all).
+---Clears the event selection used only for CalendarContext functions. The selection state cleared by this function is used only by other
+---CalendarContext functions; other calendar event functions use the selection state set by CalendarOpenEvent, CalendarNewEvent,
+---CalendarNewGuildEvent, or CalendarNewGuildAnnouncement (if they use a selection state at all).
 function CalendarContextDeselectEvent() end

api/CalendarContextEventCanComplain.lua

@@ -1,13 +1,16 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@alias monthOffset
+---| -1 month preceding the calendar's current month
+---| 0 The calendar's current month (i.e. same month as CalendarGetMonth())
+---| 1 month after the calendar's current month
+---| nil Use the event selected by CalendarContextSelectEvent and ignore further arguments
+
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---@return boolean canReport
----Returns whether the player can report an event invitation as spam. If all arguments are omitted, uses the event selected by CalendarContextSelectEvent.
-function CalendarContextEventCanComplain(monthOffset, -1, 0, 1, nil, day, index) end
+---Returns whether the player can report an event invitation as spam. If all arguments are omitted
+---uses the event selected by CalendarContextSelectEvent.
+function CalendarContextEventCanComplain(monthOffset, day, index) end

api/CalendarContextEventCanEdit.lua

@@ -1,13 +1,9 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---@return boolean canEdit
 ---Returns whether the player can edit an event
-function CalendarContextEventCanEdit(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextEventCanEdit(monthOffset, day, index) end

api/CalendarContextEventComplain.lua

@@ -1,12 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---Reports an event invitation as spam
-function CalendarContextEventComplain(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextEventComplain(monthOffset, day, index) end

api/CalendarContextEventCopy.lua

@@ -1,12 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---Copies an event for later pasting
-function CalendarContextEventCopy(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextEventCopy(monthOffset, day, index) end

api/CalendarContextEventGetCalendarType.lua

@@ -1,20 +1,18 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@alias calendarType
+---| "GUILD_ANNOUNCEMENT" Guild announcement (does not allow players to sign up)
+---| "GUILD_EVENT" Guild event (allows players to sign up)
+---| "HOLIDAY" World event (e.g. Lunar Festival, Darkmoon Faire, Stranglethorn Fishing Tournament, Call to Arms: Arathi Basin)
+---| "PLAYER" Player-created event or invitation
+---| "RAID_LOCKOUT" Indicates when one of the player's saved instances resets
+---| "RAID_RESET" Indicates scheduled reset times for major raid instances
+---| "SYSTEM" Other server-provided event
+
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
----@return SYSTEM calendarType 
----@return  GUILD_ANNOUNCEMENT 
----@return  GUILD_EVENT 
----@return  HOLIDAY 
----@return  PLAYER 
----@return  RAID_LOCKOUT 
----@return  RAID_RESET 
----@return  SYSTEM 
+---@return calendarType
 ---Returns the type of a calendar event. If all arguments are omitted, uses the event selected by CalendarContextSelectEvent.
-function CalendarContextEventGetCalendarType(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextEventGetCalendarType(monthOffset, day, index) end

api/CalendarContextEventPaste.lua

@@ -1,10 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset 1 
----@param -1  
----@param 0  
----@param 1  
+---@param monthOffset monthOffset
 ---@param day number
 ---Pastes a copied event into a given date. Does nothing if no event has been copied via CalendarContextEventCopy.
-function CalendarContextEventPaste(monthOffset, -1, 0, 1, day) end
+function CalendarContextEventPaste(monthOffset, day) end

api/CalendarContextEventRemove.lua

@@ -1,12 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---Deletes an event from the calendar
-function CalendarContextEventRemove(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextEventRemove(monthOffset, day, index) end

api/CalendarContextEventSignUp.lua

@@ -1,12 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---Signs the player up for a guild event
-function CalendarContextEventSignUp(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextEventSignUp(monthOffset, day, index) end

api/CalendarContextGetEventIndex.lua

@@ -1,11 +1,11 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@return 1 monthOffset
----@return  -1
----@return  0
----@return  1
+---@return monthOffset monthOffset
 ---@return number day
 ---@return number index
----Returns the month, day, and index of the event selection used only for CalendarContext functions. The selection state referenced by this function is used only by other CalendarContext functions; other calendar event functions use the selection state set by CalendarOpenEvent, CalendarNewEvent, CalendarNewGuildEvent, or CalendarNewGuildAnnouncement (if they use a selection state at all). Used in the default UI to implement the calendar's context menu (on right-click).
+---Returns the month, day, and index of the event selection used only for CalendarContext functions. The selection state referenced by this function
+---is used only by other CalendarContext functions; other calendar event functions use the selection state set by CalendarOpenEvent, CalendarNewEvent,
+---CalendarNewGuildEvent, or CalendarNewGuildAnnouncement (if they use a selection state at all). Used in the default UI to implement the
+---calendar's context menu (on right-click).
 function CalendarContextGetEventIndex() end

api/CalendarContextInviteAvailable.lua

@@ -1,12 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---Accepts an event invitation
-function CalendarContextInviteAvailable(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextInviteAvailable(monthOffset, day, index) end

api/CalendarContextInviteDecline.lua

@@ -1,12 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---Declines an event invitation
-function CalendarContextInviteDecline(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextInviteDecline(monthOffset, day, index) end

api/CalendarContextInviteIsPending.lua

@@ -1,13 +1,9 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---@return boolean pendingInvite
 ---Returns whether the player has been invited to an event and not yet responded
-function CalendarContextInviteIsPending(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextInviteIsPending(monthOffset, day, index) end

api/CalendarContextInviteModeratorStatus.lua

@@ -1,15 +1,13 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@alias modStatus #The player's level of authority for the event, or "" if not applicable
+---| "MODERATOR" The player has been granted moderator status for the event
+---| "CREATOR" The player is the original creator of the event
+
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
----@return MODERATOR modStatus 
----@return  CREATOR 
----@return  MODERATOR 
+---@return modStatus modStatus
 ---Returns the player's moderator status for an event
-function CalendarContextInviteModeratorStatus(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextInviteModeratorStatus(monthOffset, day, index) end

api/CalendarContextInviteRemove.lua

@@ -1,12 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---Removes an invitation from the player's calendar or removes the player from a guild event's signup list
-function CalendarContextInviteRemove(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextInviteRemove(monthOffset, day, index) end

api/CalendarContextInviteStatus.lua

@@ -1,21 +1,19 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@alias inviteStatus
+---| 1 Invited (also used for non-invitation/non-signup events)
+---| 2 Accepted
+---| 3 Declined
+---| 4 Confirmed
+---| 5 Out
+---| 6 Standby
+---| 7 Signed up
+---| 8 Not signed up
+
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
----@return 8 inviteStatus 
----@return  1 
----@return  2 
----@return  3 
----@return  4 
----@return  5 
----@return  6 
----@return  7 
----@return  8 
+---@return inviteStatus
 ---Returns the player's invite status for an event
-function CalendarContextInviteStatus(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextInviteStatus(monthOffset, day, index) end

api/CalendarContextInviteType.lua

@@ -1,15 +1,13 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@alias inviteType
+---| 1 Characters can only be explicitly invited to the event (or event is a non-invite/non-signup event)
+---| 2 Event is visible to the player's entire guild; guild members can sign up and other characters can be explicitly invited
+
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
----@return 2 inviteType 
----@return  1 
----@return  2 
+---@return inviteType
 ---Returns the invite type for an event
-function CalendarContextInviteType(monthOffset, -1, 0, 1, nil, day, index) end
+function CalendarContextInviteType(monthOffset, day, index) end

api/CalendarContextSelectEvent.lua

@@ -1,12 +1,11 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset CalendarContextSelectEvent 
----@param -1  
----@param 0  
----@param 1  
----@param nil CalendarContextSelectEvent 
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
----Selects an event for use only with other CalendarContext functions. The selection state set by this function is used only by other CalendarContext functions; other calendar event functions use the selection state set by CalendarOpenEvent, CalendarNewEvent, CalendarNewGuildEvent, or CalendarNewGuildAnnouncement (if they use a selection state at all). Used in the default UI to implement the calendar's context menu (on right-click).
-function CalendarContextSelectEvent(monthOffset, -1, 0, 1, nil, day, index) end
+---Selects an event for use only with other CalendarContext functions. The selection state set by this function is used only by other CalendarContext
+---functions; other calendar event functions use the selection state set by CalendarOpenEvent, CalendarNewEvent, CalendarNewGuildEvent,
+---or CalendarNewGuildAnnouncement (if they use a selection state at all).
+---Used in the default UI to implement the calendar's context menu (on right-click).
+function CalendarContextSelectEvent(monthOffset, day, index) end

api/CalendarEventGetCalendarType.lua

@@ -1,9 +1,6 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@return PLAYER calendarType
----@return  GUILD_ANNOUNCEMENT
----@return  GUILD_EVENT
----@return  PLAYER
+---@return calendarType
 ---Returns the type of the selected calendar event
 function CalendarEventGetCalendarType() end

api/CalendarEventGetInvite.lua

@@ -6,20 +6,9 @@
 ---@return number level
 ---@return string className
 ---@return string classFileName
----@return 7 inviteStatus
----@return  1
----@return  2
----@return  3
----@return  4
----@return  5
----@return  6
----@return  7
----@return MODERATOR modStatus
----@return  CREATOR
----@return  MODERATOR
+---@return inviteStatus
+---@return modStatus
 ---@return boolean inviteIsMine
----@return 2 inviteType
----@return  1
----@return  2
+---@return inviteType
 ---Returns information about an entry in the selected event's invite/signup list
 function CalendarEventGetInvite(index) end

api/CalendarEventGetInviteSortCriterion.lua

@@ -1,10 +1,12 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@return status criterion
----@return CLASS_SORT_ORDER class
----@return  name
----@return  status
+---@alias criterion
+---| "CLASS" Sorted by character class (according to the global table CLASS_SORT_ORDER)
+---| "NAME" Sorted by character name
+---| "STATUS" Sorted by invite status
+
+---@return criterion
 ---@return boolean reverse
 ---Returns the current sort mode for the event invite/signup list
 function CalendarEventGetInviteSortCriterion() end

api/CalendarEventGetRepeatOptions.lua

@@ -1,6 +1,6 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@return list ...
+---@return string[]
 ---Returns a list of localized event repetition option labels (currently unused)
 function CalendarEventGetRepeatOptions() end

api/CalendarEventGetStatusOptions.lua

@@ -1,6 +1,6 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@return list ...
+---@return string[]
 ---Returns a list of localized invite status labels
 function CalendarEventGetStatusOptions() end

api/CalendarEventGetTextures.lua

@@ -1,11 +1,13 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param eventType 2 
----@param 1  
----@param 2  
+---@alias eventType
+---| 1 Raid dungeon
+---| 2 Five-player dungeon
+
+---@param eventType eventType
+---@param expansion number Expansion to which the instance belongs; localized names can be found in the constants EXPANSION_NAME0, EXPANSION_NAME1, etc. (number)
 ---@return string name
----@return string icon 
----@return number expansion 
+---@return string icon #Unique part of the path to the instance's icon texture; for the full path, prepend with "Interface\LFGFrame\LFGIcon-"
 ---Returns a list of instance names and icons for dungeon or raid events
-function CalendarEventGetTextures(eventType, 1, 2) end
+function CalendarEventGetTextures(eventType, expansion) end

api/CalendarEventGetTypes.lua

@@ -1,6 +1,6 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@return list ...
+---@return string[]
 ---Returns a list of event display style labels
 function CalendarEventGetTypes() end