Refactor calendar event functions to enhance parameter aliasing and improve documentation clarity

api/CalendarEventGetTextures.lua

@@ -4,6 +4,9 @@
 ---@alias eventType
 ---| 1 Raid dungeon
 ---| 2 Five-player dungeon
+---| 3 PvP event
+---| 4 Meeting
+---| 5 Other event
 
 ---@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)

api/CalendarEventSetStatus.lua

@@ -1,15 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param index number 
----@param inviteStatus 8 
----@param 1  
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
----@param 7  
----@param 8  
+---@param index number
+---@param inviteStatus inviteStatus
 ---Sets the status of a character on the selected event's invite/signup list
-function CalendarEventSetStatus(index, inviteStatus, 1, 2, 3, 4, 5, 6, 7, 8) end
+function CalendarEventSetStatus(index, inviteStatus) end

api/CalendarEventSetType.lua

@@ -1,11 +1,6 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param eventType 5 
----@param 1  
----@param 2  
----@param 3  
----@param 4  
----@param 5  
+---@param eventType eventType
 ---Changes the display type of the selected event
-function CalendarEventSetType(eventType, 1, 2, 3, 4, 5) end
+function CalendarEventSetType(eventType) end

api/CalendarEventSortInvites.lua

@@ -1,10 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param criterion status
----@param class CLASS_SORT_ORDER
----@param name
----@param status
+---@param criterion criterion
 ---@param reverse boolean
 ---Sorts the event invite/signup list. Does not cause the list to automatically remain sorted; e.g. if sorted by status and a character's status is changed, the list will not be resorted until this function is called again.
-function CalendarEventSortInvites(criterion, class, name, status, reverse) end
+function CalendarEventSortInvites(criterion, reverse) end

api/CalendarGetDayEvent.lua

@@ -1,54 +1,30 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset 1 
----@param -1  
----@param 0  
----@param 1  
----@param day number 
----@param index number 
----@return string title 
----@return number hour 
----@return number minute 
----@return SYSTEM calendarType 
----@return  GUILD_ANNOUNCEMENT 
----@return  GUILD_EVENT 
----@return  HOLIDAY 
----@return  PLAYER 
----@return  RAID_LOCKOUT 
----@return  RAID_RESET 
----@return  SYSTEM 
----@return START sequenceType 
----@return  END 
----@return  INFO 
----@return  ONGOING 
----@return  START 
----@return 5 eventType 
----@return  0 
----@return  1 
----@return  2 
----@return  3 
----@return  4 
----@return  5 
----@return string texture 
----@return MODERATOR modStatus 
----@return  CREATOR 
----@return  MODERATOR 
----@return 8 inviteStatus 
----@return  1 
----@return  2 
----@return  3 
----@return  4 
----@return  5 
----@return  6 
----@return  7 
----@return  8 
----@return string invitedBy 
----@return 2 difficulty 
----@return  1 
----@return  2 
----@return 2 inviteType 
----@return  1 
----@return  2 
+---@alias sequenceType
+---| "END" Last day of the event
+---| "INFO" An additional specially-labeled day related the event
+---| "ONGOING" Continuation of the event
+---| "START" First day of the event
+
+---@alias difficulty
+---| 1 Normal
+---| 2 Heroic
+
+---@param monthOffset monthOffset
+---@param day number
+---@param index number #Index of an event on the given day (from 1 to CalendarGetNumDayEvents()) (number)
+---@return string title
+---@return number hour
+---@return number minute
+---@return calendarType calendarType
+---@return sequenceType sequenceType
+---@return number eventType
+---@return number texture
+---@return modStatus modStatus
+---@return inviteStatus inviteStatus
+---@return string invitedBy
+---@return difficulty difficulty
+---@return inviteType inviteType
 ---Returns information about a calendar event on a given day. Information can only be retrieved for events which might be visible in the calendar's current month -- i.e. those in the current month as well as those in (roughly) the last week of the previous month and (roughly) the first two weeks of the following month. To reliably retrieve information for events outside the calendar's current month, first change the calendar's month with CalendarSetMonth.
-function CalendarGetDayEvent(monthOffset, -1, 0, 1, day, index) end
+function CalendarGetDayEvent(monthOffset, day, index) end

api/CalendarGetEventInfo.lua

@@ -1,49 +1,27 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@return string title
----@return string description
----@return string creator
----@return 5 eventType
----@return  1
----@return  2
----@return  3
----@return  4
----@return  5
----@return number repeatOption
----@return number maxSize
----@return number textureIndex
----@return number weekday
----@return number month
----@return number day
----@return number year
----@return number hour
----@return number minute
----@return number lockoutWeekday
----@return number lockoutMonth
----@return number lockoutDay
----@return number lockoutYear
----@return number lockoutHour
----@return number lockoutMinute
----@return 1nil locked
----@return 1nil autoApprove
----@return 1nil pendingInvite
----@return 8 inviteStatus
----@return  1
----@return  2
----@return  3
----@return  4
----@return  5
----@return  6
----@return  7
----@return  8
----@return 2 inviteType
----@return  1
----@return  2
----@return SYSTEM calendarType
----@return  GUILD_ANNOUNCEMENT
----@return  GUILD_EVENT
----@return  PLAYER
----@return  SYSTEM
+---@return string title - Title displayed for the event
+---@return string description - Descriptive text about the event
+---@return string creator - Name of the character who created the event
+---@return eventType eventType - Display style for the event; used in the default UI to determine which icon to show
+---@return number repeatOption - Index of an event repetition option; currently unused (always 1)
+---@return number maxSize - Maximum number of invites/signups; currently unused (always 100)
+---@return number textureIndex - Index of the dungeon or raid instance
+---@return number weekday - Index of the day of the week on which the event starts (1 = Sunday)
+---@return number month - Index of the month in which the event starts (1 = January)
+---@return number day - Day of the month on which the event starts
+---@return number year - Year in which the event starts (full four-digit year)
+---@return number hour - Hour part of the event's start time (24-hour clock)
+---@return number minute - Minute part of the event's start time
+---@return number lockoutWeekday - Currently unused
+---@return number lockoutMonth - Currently unused
+---@return number lockoutDay - Currently unused
+---@return number lockoutYear - Currently unused
+---@return number lockoutHour - Currently unused
+---@return number lockoutMinute - Currently unused
+---@return inviteStatus inviteStatus - The player's status regarding the event
+---@return inviteType inviteType - Invitation/announcement type for the event
+---@return calendarType calendarType - Token identifying the type of event
 ---Returns information about the selected calendar event
 function CalendarGetEventInfo() end

api/CalendarGetGuildEventInfo.lua

@@ -1,42 +1,38 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
+---@alias month
+---| 1 January
+---| 2 February
+---| 3 March
+---| 4 April
+---| 5 May
+---| 6 June
+---| 7 July
+---| 8 August
+---| 9 September
+---| 10 October
+---| 11 November
+---| 12 December
+
+---@alias weekday
+---| 1 Sunday
+---| 2 Monday
+---| 3 Tuesday
+---| 4 Wednesday
+---| 5 Thursday
+---| 6 Friday
+---| 7 Saturday
+
 ---@param eventIndex number
----@return 12 month
----@return  1
----@return  2
----@return  3
----@return  4
----@return  5
----@return  6
----@return  7
----@return  8
----@return  9
----@return  10
----@return  11
----@return  12
+---@return month month
 ---@return number day
----@return 7 weekday
----@return  1
----@return  2
----@return  3
----@return  4
----@return  5
----@return  6
----@return  7
+---@return weekday weekday
 ---@return number hour
 ---@return number minute
----@return 6 eventType
----@return  1
----@return  2
----@return  3
----@return  4
----@return  5
----@return  6
+---@return eventType eventType
 ---@return string title
----@return GUILD_EVENT calendarType
----@return  GUILD_ANNOUNCEMENT
----@return  GUILD_EVENT
+---@return calendarType calendarType
 ---@return string textureName
 ---Returns information about a calendar guild-event
 function CalendarGetGuildEventInfo(eventIndex) end

api/CalendarGetHolidayInfo.lua

@@ -1,7 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset number
+---@param monthOffset monthOffset
 ---@param day number
 ---@param index number
 ---@return string name

api/CalendarGetMonth.lua

@@ -1,7 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param monthOffset number
+---@param monthOffset monthOffset
 ---@return number month
 ---@return number year
 ---@return number numDays

api/CalendarGetMonthNames.lua

@@ -1,6 +1,6 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@return list ...
+---@return string[] monthNames
 ---Returns a list of localized month names
 function CalendarGetMonthNames() end