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
 
----@param inputString string 
+---@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)
----@param includeBitfield AUTOCOMPLETE_FLAG_ALL 
+---| 0x00000000 - AUTOCOMPLETE_FLAG_NONE: No characters
----@param 0x00000000 AUTOCOMPLETE_FLAG_NONE 
+---| 0x00000001 - AUTOCOMPLETE_FLAG_IN_GROUP: Characters in the player's party or raid
----@param 0x00000001 AUTOCOMPLETE_FLAG_IN_GROUP 
+---| 0x00000002 - AUTOCOMPLETE_FLAG_IN_GUILD: Characters in the player's guild
----@param 0x00000002 AUTOCOMPLETE_FLAG_IN_GUILD 
+---| 0x00000004 - AUTOCOMPLETE_FLAG_FRIEND: Characters from the player's friends list
----@param 0x00000004 AUTOCOMPLETE_FLAG_FRIEND 
+---| 0x00000010 - AUTOCOMPLETE_FLAG_INTERACTED_WITH: Characters with whom the player has recently interacted
----@param 0x00000010 AUTOCOMPLETE_FLAG_INTERACTED_WITH 
+---| 0x00000020 - AUTOCOMPLETE_FLAG_ONLINE: Currently online friends and guildmates
----@param 0x00000020 AUTOCOMPLETE_FLAG_ONLINE 
+---| 0xffffffff - AUTOCOMPLETE_FLAG_ALL: All characters
----@param 0xffffffff AUTOCOMPLETE_FLAG_ALL 
+
----@param excludeBitfield AUTOCOMPLETE_FLAG_ALL 
+---@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)
----@param 0x00000000 AUTOCOMPLETE_FLAG_NONE 
+---| 0x00000000 - AUTOCOMPLETE_FLAG_NONE: No characters
----@param 0x00000001 AUTOCOMPLETE_FLAG_IN_GROUP 
+---| 0x00000001 - AUTOCOMPLETE_FLAG_IN_GROUP: Characters in the player's party or raid
----@param 0x00000002 AUTOCOMPLETE_FLAG_IN_GUILD 
+---| 0x00000002 - AUTOCOMPLETE_FLAG_IN_GUILD: Characters in the player's guild
----@param 0x00000004 AUTOCOMPLETE_FLAG_FRIEND 
+---| 0x00000004 - AUTOCOMPLETE_FLAG_FRIEND: Characters from the player's friends list
----@param 0x00000010 AUTOCOMPLETE_FLAG_INTERACTED_WITH 
+---| 0x00000010 - AUTOCOMPLETE_FLAG_INTERACTED_WITH: Characters with whom the player has recently interacted
----@param 0x00000020 AUTOCOMPLETE_FLAG_ONLINE 
+---| 0x00000020 - AUTOCOMPLETE_FLAG_ONLINE: Currently online friends and guildmates
----@param 0xffffffff AUTOCOMPLETE_FLAG_ALL 
+---| 0xffffffff - AUTOCOMPLETE_FLAG_ALL: All characters
----@param maxResults number 
+
----@param cursorPosition number 
+---@param inputString string
----@return list ... 
+---@param includeBitfield includeBitfield
+---@param excludeBitfield excludeBitfield
+---@param maxResults number
+---@param cursorPosition number
+---@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 styleIndex barberShopStyleIndex
----@param 1  
+---@return string name
----@param 2  
+---@return string unused
----@param 3  
+---@return number cost
----@return string name 
+---@return 1nil isCurrent
----@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 
+---@alias battlegroundGroup
----@param 0  
+---| 0 - Green Team/Horde
----@param 1  
+---| 1 - Gold Team/Alliance
----@return string teamName 
+
----@return number teamRating 
+---@param index battlegroundGroup
----@return number newTeamRating 
+---@return string teamName
----@return number teamMMR 
+---@return number teamRating
----@return number numPlayers 
+---@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 func function
----@param includeSubroutines boolean 
+---@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 
+---@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 
+---@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

@@ -1,11 +1,8 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param socket number 
+---@param socket number
----@param talentGroup nil 
+---@param talentGroup talentGroup
----@param 1  
+---@return string link
----@param 2  
----@param nil  
----@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

@@ -1,15 +1,12 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param socket number 
+---@param socket number
----@param talentGroup nil 
+---@param talentGroup talentGroup
----@param 1  
+---@return boolean enabled
----@param 2  
+---@return number glyphType
----@param nil  
+---@return number glyphTooltipIndex
----@return boolean enabled 
+---@return number glyphSpell
----@return number glyphType 
+---@return string icon
----@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
 
----@param name string 
+---@alias gender
----@param gender 3 
+---| 1 or nil - Neuter
----@param 1 or nil  
+---| 2 - Male
----@param 2  
+---| 3 - Female
----@param 3  
+
----@return number numSets 
+---@param name string
+---@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,13 +1,23 @@
 ---@diagnostic disable: missing-return, lowercase-global
 ---@meta
 
----@param nil number 
+---@param index number
----@return string name 
+---@return string name
----@return string rank 
+---@return string rank
----@return string texture 
+---@return string texture
----@return number duration 
+---@return number duration
----@return number expiration 
+---@return number expiration
----@return number spellId 
+---@return number spellId
----@return number slot 
+---@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.
+--- 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:
-function GetRaidBuffTrayAuraInfo(nil) end
+--  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 slot runeSlot
----@param 1  
+---@return number start
----@param 2  
+---@return number duration
----@param 3  
+---@return boolean runeReady
----@param 4  
----@param 5  
----@param 6  
----@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 slot runeSlot
----@param 1  
+---@return number count
----@param 2  
----@param 3  
----@param 4  
----@param 5  
----@param 6  
----@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