diff --git a/src/gui.lua b/src/gui.lua
index 28cdc3f..cb89c77 100644
--- a/src/gui.lua
+++ b/src/gui.lua
@@ -1,3 +1,10 @@
+--
+-- gui.lua
+--
+-- Contains the main GUI module. This module is responsible
+-- for the main frame of the addon.
+--
+
local addonName, addonTable = ...
-- Global functions for faster access
@@ -380,6 +387,8 @@ function gui:ToggleParseFilter(attribute, value)
end
end
+-- Updates the currently selected filters box to match
+-- the filters selected.
function gui:DisplayParseFilters()
self.filterContainer:ReleaseChildren();
diff --git a/src/highscore.lua b/src/highscore.lua
index a6d947b..fc673ca 100644
--- a/src/highscore.lua
+++ b/src/highscore.lua
@@ -1,3 +1,13 @@
+--
+-- highscore.lua
+--
+-- Contains the highscore module. Essentially the database
+-- store for the addon, using Ace3 DB.
+--
+-- This module also has various getters for the GUI to grab
+-- data out of the database.
+--
+
local addonName, addonTable = ...
-- Global functions for faster access
@@ -343,7 +353,7 @@ function highscore:GetGuildNameById(guildId)
-- As our implementation uses the guild name as
-- id, we will simply return the value passed in.
-- Checking for actual existance is not easy due
- -- to aceDB defaults and is therefor not done.
+ -- to aceDB defaults and is therefore not done.
return guildId;
end
diff --git a/src/inspect.lua b/src/inspect.lua
index 1a1abf1..78387de 100644
--- a/src/inspect.lua
+++ b/src/inspect.lua
@@ -1,3 +1,21 @@
+--
+-- inspect.lua
+--
+-- Contains the inspect module. The inspect module
+-- is used for getting additional information about
+-- players that can only be gotten by doing an inspection
+-- of them. These datas are item level and spec.
+--
+-- The module has an inspectCache that is used to reduce
+-- the number of inspects required, as inspects are quite
+-- slow to perform. This cache is automatically added to
+-- for every successful inspect.
+--
+-- The module tries to inspect the raid whenever the player
+-- enters a raid instance and clears the inspect cache when
+-- the player leaves the group.
+--
+
local addonName, addonTable = ...
-- Global functions for faster access
@@ -13,6 +31,9 @@ addon.inspect = inspect;
-- How many seconds before a cached inspect is considered invalid.
local INSPECT_CACHE_TIMEOUT = 60*60;
+-- How many seconds before an attempted inspect is canceled.
+local INSPECT_CANCEL_TIMEOUT = 1;
+
local INVENTORY_SLOT_NAMES = {
"HeadSlot","NeckSlot","ShoulderSlot","BackSlot","ChestSlot","WristSlot",
"HandsSlot","WaistSlot","LegsSlot","FeetSlot","Finger0Slot","Finger1Slot",
@@ -26,15 +47,20 @@ local NOOP = function() end
local PLAYER_GUID = nil;
--- A map from player GUID to an object {itemLevel, specName, time}
+-- A map from player GUID to an object: {itemLevel, specName, time}
local inspectCache = {};
+-- Function returning true if the player is currently in a
+-- PVE instance.
local function isInPVEInstance()
local isInstance, instanceType = IsInInstance();
return inInstance and (instanceType == "party" or instanceType == "raid")
end
+-- Attempts to get the talent spec name of the provided unitName.
+-- The unitName must either be "player" or a unit currently being
+-- inspected.
local function getTalentSpec(unitName)
if unitName == "player" then
local spec = GetSpecialization();
@@ -54,6 +80,9 @@ local function getTalentSpec(unitName)
end
end
+-- Attempts to get the item level of the provided unitName.
+-- The unitName must either be "player" or a unit currently being
+-- inspected.
local function getItemLevel(unitName)
if unitName == "player" then
local _, equipped = GetAverageItemLevel();
@@ -81,6 +110,9 @@ local function getItemLevel(unitName)
end
end
+-- Returns true if the inspectCache has an entry for the playerId
+-- specified. If the optional ignoreExpired flag is true, then
+-- this function will not check the time of the stored entry.
local function hasPlayerInspectCache(playerId, ignoreExpired)
if inspectCache[playerId] and ignoreExpired then
return true -- We have a cache, might be expired
@@ -94,10 +126,14 @@ local function hasPlayerInspectCache(playerId, ignoreExpired)
end
end
+-- Removes any entry for the specified playerId from the
+-- inspectCache.
local function unsetPlayerInspectCache(playerId)
inspectCache[playerId] = nil;
end
+-- Sets the entry for a player with the specified playerId to match
+-- the provided values.
local function setPlayerInspectCache(playerId, specName, itemLevel)
inspectCache[playerId] = {};
inspectCache[playerId].specName = specName;
@@ -110,16 +146,18 @@ local function setPlayerInspectCache(playerId, specName, itemLevel)
end
end
+-- Starts the timer for doing inspects, if not already started.
function inspect:StartNotifyInspectTimer()
if not self.notifyInspectTimer then
self:Debug("Starting notifyInspectTimer");
self.notifyInspectTimer = self:ScheduleRepeatingTimer(function()
self:OnNotifyInspectTimerDone()
- end, 1);
+ end, INSPECT_CANCEL_TIMEOUT);
end
end
+-- Stops the NotifyInspect timer, if not already stopped.
function inspect:StopNotifyInspectTimer()
if self.notifyInspectTimer then
self:Debug("Stopping notifyInspectTimer");
@@ -129,6 +167,9 @@ function inspect:StopNotifyInspectTimer()
end
end
+-- Adds a player object to the queue of players to inspect.
+-- The provided callback will be called with the result of the
+-- inspect when done.
function inspect:QueueInspect(player, callback)
self:Debug("QueueInspect", player.name)
@@ -140,6 +181,11 @@ function inspect:QueueInspect(player, callback)
self:StartNotifyInspectTimer();
end
+-- Attempts to set fields on the player object by using
+-- cached data from the inspectCage. Returns true if data
+-- was available and not expired. False if no data could be
+-- found or the data was expired. Note that data will be added
+-- to the player object even if the data is expired.
function inspect:SetCachedInspectDataForPlayer(player)
if player.id == PLAYER_GUID then
player.specName = getTalentSpec("player")
@@ -159,6 +205,8 @@ function inspect:SetCachedInspectDataForPlayer(player)
end
end
+-- Helper method for getting inspect data for a single player,
+-- calling the provided callback on success/error.
function inspect:GetInspectDataForPlayer(player, callback)
-- Make sure we always have a callback
callback = callback and callback or NOOP;
@@ -172,6 +220,10 @@ function inspect:GetInspectDataForPlayer(player, callback)
end
end
+-- Takes a list of player objects and tries to get inspect data
+-- for all these objects. The player objects are modified in place.
+-- The callback is called when attempt for all players has been
+-- performed.
function inspect:GetInspectDataForPlayers(players, callback)
local totalCallbacks = #players;
local doneCallbacks = 0;
@@ -186,6 +238,8 @@ function inspect:GetInspectDataForPlayers(players, callback)
end
end
+-- Tries to pre-inspect all guild members of a raid group
+-- to populate the inspectCache for the players.
function inspect:PreInspectGroup()
for i=1, GetNumGroupMembers() do
@@ -201,6 +255,10 @@ function inspect:PreInspectGroup()
end
end
+-- Resolves a pending inspect for playerId. If successful
+-- sets the player object's data to the new values. Calls
+-- all callbacks registered for this player id and removes
+-- the player id from the queue of inspects.
function inspect:ResolveInspect(playerId, success)
if not self.inspectQueue[playerId] then
return
@@ -230,6 +288,11 @@ function inspect:ResolveInspect(playerId, success)
end
end
+-- Called once every INSPECT_CANCEL_TIMEOUT seconds. If a
+-- sent inspect request is currently pending this request will
+-- be canceld and considered failed.
+-- If any inspects are queued a request for a new inspect is
+-- sent.
function inspect:OnNotifyInspectTimerDone()
-- Timeout any current inspection
if self.currentInspectPlayerId then
diff --git a/src/main.lua b/src/main.lua
index fc2266a..2dbedaf 100644
--- a/src/main.lua
+++ b/src/main.lua
@@ -1,3 +1,13 @@
+--
+-- main.lua
+--
+-- Contains the main setup code for the addon and the modules and
+-- some shared code that is used throughout the addon.
+-- Also handles the quering of the parse module on ENCOUNTER_END
+-- and forwarding these results, via the inspect module, to the
+-- highscore module.
+--
+
local addonName, addonTable = ...
local tinsert = tinsert;
@@ -39,6 +49,9 @@ DEBUG_PRINT = false;
DEBUG_PRINT = true;
--@end-debug@
+
+-- Takes a difficulty ID and attempts to return a string
+-- representation of that difficulty.
local function getDifficultyNameById(difficultyId)
if difficultyId == 7 or difficultyId == 17 then
return "LFR";
@@ -53,12 +66,16 @@ local function getDifficultyNameById(difficultyId)
return nil
end
+-- A wrapper around :Pring that only prints if the
+-- DEBUG_PRINT flag is set to true.
function addon:Debug(...)
if DEBUG_PRINT then
self:Print(...)
end
end
+-- Function that updates the guild name of the player
+-- by quering the GetGuildInfo method for the player.
function addon:UpdateMyGuildName()
if IsInGuild() then
local guildName, _, _ = GetGuildInfo("player")
@@ -70,12 +87,16 @@ function addon:UpdateMyGuildName()
end
end
+-- Sets the current zone to the zone the player
+-- is currently in.
function addon:UpdateCurrentZone()
local zoneId, _ = GetCurrentMapAreaID()
local zoneName = GetRealZoneText();
self.currentZone = {id = zoneId, name = zoneName};
end
+-- Tests if a player with name playerName is in the same
+-- guild as the player running this addon.
function addon:IsInMyGuild(playerName)
if self.guildName then
local guildName, _, _ = GetGuildInfo(playerName)
@@ -85,6 +106,13 @@ function addon:IsInMyGuild(playerName)
end
end
+-- Method called when ENCOUNTER_END was called and the success
+-- status was true.
+-- This method uses the parse module to get a list of all valid
+-- parses. It then uses the inspect module to get additional
+-- information for the players with parses. Finally it forwards
+-- the results to the highscore module for it to store the data
+-- in the database.
function addon:OnEncounterEndSuccess(encounterId, encounterName, difficultyId, raidSize)
self:Debug("OnEncounterEndSuccess")
@@ -110,16 +138,20 @@ function addon:OnEncounterEndSuccess(encounterId, encounterName, difficultyId, r
raidSize = raidSize
};
- local pmc = self.parseModulesCore;
- pmc:GetParsesForEncounter(encounter, function(success, startTime, duration, players)
- if not success then return end;
+ local function handleInspectData()
+ addon.highscore:AddEncounterParsesForPlayers(guildName, encounter, players);
+ end
+ local function handleParses(success, startTime, duration, players)
+ if not success then return end;
encounter.startTime = startTime;
encounter.duration = duration;
- self.inspect:GetInspectDataForPlayers(players, function()
- self.highscore:AddEncounterParsesForPlayers(guildName, encounter, players);
- end)
- end)
+ addon.inspect:GetInspectDataForPlayers(players, handleInspectData);
+ end
+
+ -- Get parses from the parse provider
+ local pmc = self.parseModulesCore;
+ pmc:GetParsesForEncounter(encounter, handleParses);
end
function addon:PLAYER_GUILD_UPDATE(evt, unitId)
@@ -130,7 +162,8 @@ end
function addon:ENCOUNTER_END(evt, encounterId, encounterName, difficultyId, raidSize, endStatus)
self:Debug("ENCOUNTER_END", encounterId, encounterName, difficultyId, raidSize, endStatus)
- if endStatus == 1 then -- Success
+ if endStatus == 1 then
+ -- Encounter killed successful
self:OnEncounterEndSuccess(encounterId, encounterName, difficultyId, raidSize);
end
end
diff --git a/src/parse_modules/parse_modules_core.lua b/src/parse_modules/parse_modules_core.lua
index 6040a6b..3753eb7 100644
--- a/src/parse_modules/parse_modules_core.lua
+++ b/src/parse_modules/parse_modules_core.lua
@@ -1,6 +1,13 @@
+--
+-- parse_modules_core.lua
+--
+-- Contains the core module for the parse modules. This module
+-- is responsible for picking one of the parse modules that
+-- can be activated and then forwarding requests for parses to
+-- the selected parse provider.
--
--- The parseModulesCore is a container module for our
--- parse provider modules.
+-- A parse provider is a module that uses some damage mod (e.g. Skada)
+-- and returns parses from the last encounter when asked for.
--
local addonName, addonTable = ...
@@ -69,7 +76,7 @@ end
-- Function for getting parses for an encounter. This
-- function will forward the call to the selected parse
-- provider if available. Will also add additional information
--- like spec and role to successful parse fetches
+-- like class and role to successful parse fetches
function pmc:GetParsesForEncounter(encounter, callback)
local parseProvider = self.selectedParseProvider
if parseProvider then