Refactor API functions to improve parameter aliasing and enhance documentation clarity

api/GetAutoCompleteResults.lua

@@ -1,25 +1,29 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
+---@alias includeBitfield #One or more of the following flags (combined via bit.bor()), indicating which characters should be included in the result list: (number, bitfield)
+---| 0x00000000 - AUTOCOMPLETE_FLAG_NONE: No characters
+---| 0x00000001 - AUTOCOMPLETE_FLAG_IN_GROUP: Characters in the player's party or raid
+---| 0x00000002 - AUTOCOMPLETE_FLAG_IN_GUILD: Characters in the player's guild
+---| 0x00000004 - AUTOCOMPLETE_FLAG_FRIEND: Characters from the player's friends list
+---| 0x00000010 - AUTOCOMPLETE_FLAG_INTERACTED_WITH: Characters with whom the player has recently interacted
+---| 0x00000020 - AUTOCOMPLETE_FLAG_ONLINE: Currently online friends and guildmates
+---| 0xffffffff - AUTOCOMPLETE_FLAG_ALL: All characters
+
+---@alias excludeBitfield #One or more of the following flags (combined via bit.bor()), indicating which characters should be excluded from the result list: (number, bitfield)
+---| 0x00000000 - AUTOCOMPLETE_FLAG_NONE: No characters
+---| 0x00000001 - AUTOCOMPLETE_FLAG_IN_GROUP: Characters in the player's party or raid
+---| 0x00000002 - AUTOCOMPLETE_FLAG_IN_GUILD: Characters in the player's guild
+---| 0x00000004 - AUTOCOMPLETE_FLAG_FRIEND: Characters from the player's friends list
+---| 0x00000010 - AUTOCOMPLETE_FLAG_INTERACTED_WITH: Characters with whom the player has recently interacted
+---| 0x00000020 - AUTOCOMPLETE_FLAG_ONLINE: Currently online friends and guildmates
+---| 0xffffffff - AUTOCOMPLETE_FLAG_ALL: All characters
+
 ---@param inputString string
----@param includeBitfield AUTOCOMPLETE_FLAG_ALL 
----@param 0x00000000 AUTOCOMPLETE_FLAG_NONE 
----@param 0x00000001 AUTOCOMPLETE_FLAG_IN_GROUP 
----@param 0x00000002 AUTOCOMPLETE_FLAG_IN_GUILD 
----@param 0x00000004 AUTOCOMPLETE_FLAG_FRIEND 
----@param 0x00000010 AUTOCOMPLETE_FLAG_INTERACTED_WITH 
----@param 0x00000020 AUTOCOMPLETE_FLAG_ONLINE 
----@param 0xffffffff AUTOCOMPLETE_FLAG_ALL 
----@param excludeBitfield AUTOCOMPLETE_FLAG_ALL 
----@param 0x00000000 AUTOCOMPLETE_FLAG_NONE 
----@param 0x00000001 AUTOCOMPLETE_FLAG_IN_GROUP 
----@param 0x00000002 AUTOCOMPLETE_FLAG_IN_GUILD 
----@param 0x00000004 AUTOCOMPLETE_FLAG_FRIEND 
----@param 0x00000010 AUTOCOMPLETE_FLAG_INTERACTED_WITH 
----@param 0x00000020 AUTOCOMPLETE_FLAG_ONLINE 
----@param 0xffffffff AUTOCOMPLETE_FLAG_ALL 
+---@param includeBitfield includeBitfield
+---@param excludeBitfield excludeBitfield
 ---@param maxResults number
 ---@param cursorPosition number
----@return list ... 
+---@return string[] results
 ---Returns a list of character names which complete a given partial name prefix
-function GetAutoCompleteResults(inputString, includeBitfield, 0x00000000, 0x00000001, 0x00000002, 0x00000004, 0x00000010, 0x00000020, 0xffffffff, excludeBitfield, 0x00000000, 0x00000001, 0x00000002, 0x00000004, 0x00000010, 0x00000020, 0xffffffff, maxResults, cursorPosition) end
+function GetAutoCompleteResults(inputString, includeBitfield, excludeBitfield, maxResults, cursorPosition) end

api/GetBarberShopStyleInfo.lua

@@ -1,13 +1,10 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param styleIndex 3 
----@param 1  
----@param 2  
----@param 3  
+---@param styleIndex barberShopStyleIndex
 ---@return string name
 ---@return string unused
 ---@return number cost
 ---@return 1nil isCurrent
 ---Returns information about the selected barber shop style option
-function GetBarberShopStyleInfo(styleIndex, 1, 2, 3) end
+function GetBarberShopStyleInfo(styleIndex) end

api/GetBattlefieldTeamInfo.lua

@@ -1,13 +1,15 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param index 1 
----@param 0  
----@param 1  
+---@alias battlegroundGroup
+---| 0 - Green Team/Horde
+---| 1 - Gold Team/Alliance
+
+---@param index battlegroundGroup
 ---@return string teamName
 ---@return number teamRating
 ---@return number newTeamRating
 ---@return number teamMMR
 ---@return number numPlayers
 ---Returns info about teams and their rating and MMR in a rated arena match. Usable following the UPDATE_BATTLEFIELD_SCORE event.
-function GetBattlefieldTeamInfo(index, 0, 1) end
+function GetBattlefieldTeamInfo(index) end

api/GetFunctionCPUUsage.lua

@@ -1,9 +1,9 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param function function 
----@param includeSubroutines boolean 
----@return number usage 
----@return number calls 
+---@param func function
+---@param includeSubroutines boolean #True to include time spent in other functions called by the given function; false to count only time spent in the function body (boolean)
+---@return number usage #Amount of CPU time used by the function (in milliseconds) since the UI was loaded or ResetCPUUsage() was last called (number)
+---@return number calls #Number of times the function has been called (number)
 ---Returns information about CPU usage by a function. Only returns valid data if the scriptProfile CVar is set to 1; returns 0 otherwise.
-function GetFunctionCPUUsage(function, includeSubroutines) end
+function GetFunctionCPUUsage(func, includeSubroutines) end

api/GetGlyphLink.lua

@@ -2,10 +2,7 @@
 ---@meta
 
 ---@param socket number
----@param talentGroup nil 
----@param 1  
----@param 2  
----@param nil  
+---@param talentGroup talentGroup
 ---@return string link
 ---Gets a hyperlink for the contents of a glyph socket. Glyph links are distinct from item and spell links: e.g. "|cff66bbff|Hglyph:21:361|h[Glyph of Hunter's Mark]|h|r".
-function GetGlyphLink(socket, talentGroup, 1, 2, nil) end
+function GetGlyphLink(socket, talentGroup) end

api/GetGlyphSocketInfo.lua

@@ -2,14 +2,11 @@
 ---@meta
 
 ---@param socket number
----@param talentGroup nil 
----@param 1  
----@param 2  
----@param nil  
+---@param talentGroup talentGroup
 ---@return boolean enabled
 ---@return number glyphType
 ---@return number glyphTooltipIndex
 ---@return number glyphSpell
 ---@return string icon
 ---Returns information about a glyph socket and its contents. The spell ID referenced in the third return glyphSpell refers to the spell used to put the glyph in the socket -- not the Inscription spell that creates a glyph item, but the spell associated with that item's "Use:" effect.
-function GetGlyphSocketInfo(socket, talentGroup, 1, 2, nil) end
+function GetGlyphSocketInfo(socket, talentGroup) end

api/GetNumDeclensionSets.lua

@@ -1,11 +1,12 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
+---@alias gender
+---| 1 or nil - Neuter
+---| 2 - Male
+---| 3 - Female
+
 ---@param name string
----@param gender 3 
----@param 1 or nil  
----@param 2  
----@param 3  
----@return number numSets 
+---@param gender gender
 ---Returns the number of suggested declension sets for a name. Used in the Russian localized World of Warcraft client; see DeclineName for further details. Returns 0 in other locales.
-function GetNumDeclensionSets(name, gender, 1 or nil, 2, 3) end
+function GetNumDeclensionSets(name, gender) end

api/GetRaidBuffTrayAuraInfo.lua

@@ -1,7 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param nil number 
+---@param index number
 ---@return string name
 ---@return string rank
 ---@return string texture
@@ -9,5 +9,15 @@
 ---@return number expiration
 ---@return number spellId
 ---@return number slot
----Returns the active buff for a given raid buff category. As of 5.0, the default BuffFrames aggregate standard raid buffs. GetRaidBuffTrayAuraInfo is used to determine which buff category is active. Current raid buff categories are:  RAID_BUFF_1 Stats RAID_BUFF_2 Stamina RAID_BUFF_3 Attack Power RAID_BUFF_4 Haste RAID_BUFF_5 Spell Power RAID_BUFF_6 Critical Strike RAID_BUFF_7 Mastery RAID_BUFF_8 Multistrike RAID_BUFF_9 Versatility  The highest raid buff category number is indicated by NUM_LE_RAID_BUFF_TYPES.
-function GetRaidBuffTrayAuraInfo(nil) end
+--- Returns the active buff for a given raid buff category. As of 5.0, the default BuffFrames aggregate standard raid buffs. GetRaidBuffTrayAuraInfo is used to determine which buff category is active. Current raid buff categories are:
+--  RAID_BUFF_1 Stats
+--  RAID_BUFF_2 Stamina
+--  RAID_BUFF_3 Attack Power
+--  RAID_BUFF_4 Haste
+--  RAID_BUFF_5 Spell Power
+--  RAID_BUFF_6 Critical Strike
+--  RAID_BUFF_7 Mastery
+--  RAID_BUFF_8 Multistrike
+--  RAID_BUFF_9 Versatility
+-- The highest raid buff category number is indicated by NUM_LE_RAID_BUFF_TYPES.
+function GetRaidBuffTrayAuraInfo(index) end

api/GetRuneCooldown.lua

@@ -1,15 +1,9 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param slot 6 
----@param 1  
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
+---@param slot runeSlot
 ---@return number start
 ---@return number duration
 ---@return boolean runeReady
 ---Returns cooldown information about one of the player's rune resources. Note the placement of runes 3-4 (normally Unholy) and 5-6 (normally Frost) are reversed in the default UI. Also note the behavior of returned values differs slightly from most other GetXYZCooldown-style functions.
-function GetRuneCooldown(slot, 1, 2, 3, 4, 5, 6) end
+function GetRuneCooldown(slot) end

api/GetRuneCount.lua

@@ -1,13 +1,7 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param slot 6 
----@param 1  
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
+---@param slot runeSlot
 ---@return number count
 ---Returns the number of available rune resources in one of the player's rune slots. Returns 1 if a rune is ready and 0 if a rune is on cooldown.
-function GetRuneCount(slot, 1, 2, 3, 4, 5, 6) end
+function GetRuneCount(slot) end