neodoc

gamemodes/terrortown/gamemode/client/cl_vskin/default_skin.lua

@@ -2226,6 +2226,11 @@ function SKIN:PaintWeaponPreviewTTT2(panel, w, h)
     end
 end
 
+---
+-- @param Panel panel
+-- @param number w
+-- @param number h
+-- @realm client
 function SKIN:PaintPlayerGraphTTT2(panel, w, h)
     local renderData = panel.renderData
     local padding = panel:GetPadding()

gamemodes/terrortown/gamemode/client/cl_vskin/vgui/dpippanel_ttt2.lua

@@ -4,11 +4,21 @@
 
 local PANEL = {}
 
+---
+-- @accessor string
+-- @realm client
 AccessorFunc(PANEL, "Padding", "Padding", FORCE_NUMBER)
+---
+-- @accessor number
+-- @realm client
 AccessorFunc(PANEL, "innerPadding", "InnerPadding", FORCE_NUMBER)
+---
+-- @accessor number
+-- @realm client
 AccessorFunc(PANEL, "pipOuterOffset", "OuterOffset", FORCE_NUMBER)
 
---- @ignore
+---
+-- @ignore
 function PANEL:Init()
     self:SetPadding(0)
     self:SetInnerPadding(2)
@@ -19,8 +29,11 @@ function PANEL:Init()
 end
 
 ---
--- @param pnl Panel
--- other args are DOCK enum values
+-- Adds a child panel. The first such panel is the "main" panel, and appears larger than the others. All others are positioned over the main, according to their alignment.
+-- @param Panel|string|table pnl The panel to add. If it is an actual panel, added directly. Otherwise, the name/table of a panel to create.
+-- @param DOCK ... Alignment. Only LEFT, RIGHT, TOP, and BOTTOM are valid. The first specified direction specifies the preferred axis (the axis along which it will be moved to prevent overlap).
+-- @return The added panel.
+-- @realm client
 function PANEL:Add(pnl, ...)
     local realPnl
     if ispanel(pnl) then
@@ -51,6 +64,9 @@ function PANEL:Add(pnl, ...)
     return realPnl
 end
 
+---
+-- Clears this panel.
+-- @realm client
 function PANEL:Clear()
     if self.mainPanel then
         self.mainPanel:Remove()
@@ -89,6 +105,8 @@ local axisSizeTbl = {
     [axisY] = "h",
 }
 
+---
+-- @ignore
 function PANEL:PerformLayout()
     --self:InvalidateChildren() -- Make sure we invoke our childrens' layout functions
 

gamemodes/terrortown/gamemode/client/cl_vskin/vgui/dplayergraph_ttt2.lua

@@ -6,10 +6,25 @@ local PANEL = {}
 
 local TryT = LANG.TryTranslation
 
+---
+-- @accessor string
+-- @realm client
 AccessorFunc(PANEL, "font", "Font", FORCE_STRING)
+---
+-- @accessor string
+-- @realm client
 AccessorFunc(PANEL, "title", "Title", FORCE_STRING)
-AccessorFunc(PANEL, "sortMode", "SortMode")
+---
+-- @accessor number
+-- @realm client
+AccessorFunc(PANEL, "sortMode", "SortMode", FORCE_NUMBER)
+---
+-- @accessor number
+-- @realm client
 AccessorFunc(PANEL, "padding", "Padding", FORCE_NUMBER)
+---
+-- @accessor number
+-- @realm client
 AccessorFunc(PANEL, "minWidth", "MinWidth", FORCE_NUMBER)
 
 GRAPH_SORT_MODE_NONE = 0
@@ -27,6 +42,8 @@ local graphSortModeNames = {
     [GRAPH_SORT_MODE_PLAYER_NAME] = "graph_sort_mode_player_name",
 }
 
+---
+-- @ignore
 function PANEL:Init()
     self.players = {}
     self:SetTitle("")
@@ -40,6 +57,11 @@ function PANEL:Init()
     self:SetMinWidth(100)
 end
 
+---
+-- Gets or sets whether this pannel allows user-controlled sort mode.
+-- @param nil|boolean allow Whether to allow user sorting. If nil, no change is made.
+-- @return boolean Whether user sorting is currently allowed.
+-- @realm client
 function PANEL:AllowUserSort(allow)
     if allow == nil then
         return self.allowUserSort
@@ -70,6 +92,12 @@ function PANEL:AllowUserSort(allow)
     return allow
 end
 
+---
+-- Adds a player to the graph.
+-- @param Player ply The player to add.
+-- @param number value The value associated with the player.
+-- @param nil|boolean highlight Whether the player should be highlighted. Defaults to false.
+-- @realm client
 function PANEL:AddPlayer(ply, value, highlight)
     local plyIcon = vgui.Create("SimpleIconAvatar", self)
     plyIcon:SetPlayer(ply)
@@ -86,15 +114,23 @@ function PANEL:AddPlayer(ply, value, highlight)
     self:InvalidateLayout()
 end
 
+---
+-- Clears the graph.
+-- @realm client
 function PANEL:Clear()
     self.players = {}
     local lastUserSort = self:AllowUserSort()
     self:AllowUserSort(false)
-    self:Clear()
+    local children = self:GetChildren()
+    for i = 1, #children do
+        children[i]:Remove()
+    end
     self:AllowUserSort(lastUserSort)
     self:InvalidateLayout()
 end
 
+---
+-- @ignore
 function PANEL:PerformLayout()
     local order = {}
     local orderFn

gamemodes/terrortown/gamemode/shared/sh_roleinspect.lua

@@ -25,10 +25,18 @@ roleinspect.stageNames = {
     [ROLEINSPECT_STAGE_FINAL] = "final",
 }
 
+---
+-- Gets the short form of the name of the stage.
+-- @param ROLEINSPECT_STAGE stage
+-- @realm shared
 function roleinspect.GetStageName(stage)
     return roleinspect.stageNames[stage]
 end
 
+---
+-- Gets the full language key name of the stage.
+-- @param ROLEINSPECT_STAGE stage
+-- @realm shared
 function roleinspect.GetStageFullName(stage)
     return "roleinspect_stage_" .. roleinspect.stageNames[stage]
 end
@@ -49,10 +57,18 @@ roleinspect.decisionNames = {
     [ROLEINSPECT_DECISION_ROLE_NOT_ASSIGNED] = "role_not_assigned",
 }
 
+---
+-- Gets the short form of the name of the decision.
+-- @param ROLEINSPECT_DECISION stage
+-- @realm shared
 function roleinspect.GetDecisionName(decision)
     return roleinspect.decisionNames[decision]
 end
 
+---
+-- Gets the full language key name of the decision.
+-- @param ROLEINSPECT_DECISION stage
+-- @realm shared
 function roleinspect.GetDecisionFullName(decision)
     return "roleinspect_decision_" .. roleinspect.decisionNames[decision]
 end
@@ -85,11 +101,16 @@ ROLEINSPECT_REASON_CHANCE = "roleinspect_reason_chance" -- Player assigned role
 ROLEINSPECT_REASON_WEIGHTED_CHANCE = "roleinspect_reason_weighted_chance" -- Player assigned role through weighted random selection
 ROLEINSPECT_REASON_NOT_ASSIGNED = "roleinspect_reason_not_assigned" -- Player assigned a role because they were not otherwise assigned one
 
+local getDecisionsImpl
+
 if SERVER then
     roleinspect.decisions = {}
+    ---
+    -- Enables recording information for role inspection.
+    -- @realm server
     roleinspect.cvar = CreateConVar("ttt2_roleinspect_enable", "0", { FCVAR_ARCHIVE, FCVAR_NOTIFY })
 
-    function roleinspect.GetDecisions(callback)
+    getDecisionsImpl = function(callback)
         callback(roleinspect.decisions)
     end
 
@@ -126,15 +147,24 @@ if SERVER then
         return data
     end
 
-    -- TODO: make roleinspection conditional on whether a client wants it
-
     local riEnabled = false
 
+    ---
+    -- Resets the decision table. Called at the start of role selection.
+    -- @realm server
     function roleinspect.Reset()
         roleinspect.decisions = {}
         riEnabled = roleinspect.cvar:GetBool()
     end
 
+    ---
+    -- Reports auxiliary information about a role selection stage.
+    -- @note Multiple calls are allowed; the data from each is added to a list.
+    -- @note The provided data will be deep-cloned as needed to preserve the current state.
+    -- @param ROLEINSPECT_STAGE stage The stage to associate information with
+    -- @param string key The key to record the information in.
+    -- @param any|function info The value to record, or a function which lazily creates the value to record.
+    -- @realm server
     function roleinspect.ReportStageExtraInfo(stage, key, info)
         if not riEnabled then
             return
@@ -144,6 +174,15 @@ if SERVER then
         tbl[#tbl + 1] = MaybeClone(isfunction(info) and info() or info)
     end
 
+    ---
+    -- Reports auxiliary information about a role in a given stage.
+    -- @note Multiple calls are allowed; the data from each is added to a list.
+    -- @note The provided data will be deep-cloned as needed to preserve the current state.
+    -- @param ROLEINSPECT_STAGE stage The stage to associate information with
+    -- @param number role The role index ot associate with.
+    -- @param string key The key to record the information in.
+    -- @param any|function info The value to record, or a function which lazily creates the value to record.
+    -- @realm server
     function roleinspect.ReportRoleExtraInfo(stage, role, key, info)
         if not riEnabled then
             return
@@ -153,6 +192,16 @@ if SERVER then
         tbl[#tbl + 1] = MaybeClone(isfunction(info) and info() or info)
     end
 
+    ---
+    -- Reports a role selection decision.
+    -- @note Extra data will be dep cloned, as in the *ExtraInfo functions.
+    -- @param ROLEINSPECT_STAGE stage The stage the decision was made in.
+    -- @param number role The role index the decision was made about.
+    -- @param nil|Player ply The player to associate with the role, if relevant.
+    -- @param ROLEINSPECT_DECISION decision The decision which was made.
+    -- @param ROLEINSPECT_REASON reason The reason the decision was made.
+    -- @param nil|any|function extra Extra data to record about the decision, or a function which lazily creates that extra data.
+    -- @realm server
     function roleinspect.ReportDecision(stage, role, ply, decision, reason, extra)
         if not riEnabled then
             return
@@ -172,6 +221,7 @@ if SERVER then
         if not admin.IsAdmin(ply) then
             -- send back an empty table so we always respond
             net.SendStream("TTT2SyncRoleInspectInfo", {}, { ply })
+            return
         end
 
         -- otherwise, send back the full decision table
@@ -182,7 +232,7 @@ end
 if CLIENT then
     local recvCallbacks = {}
 
-    function roleinspect.GetDecisions(callback)
+    getDecisionsImpl = function(callback)
         recvCallbacks[#recvCallbacks + 1] = callback
 
         net.Start("TTT2SyncRoleInspectInfo")
@@ -196,3 +246,11 @@ if CLIENT then
         end
     end)
 end
+
+---
+-- Gets the decision table recorded by roleinspect.
+-- @note When called on the server, the callback is provided with the actual decision table reference.
+-- @note When called on a client which does not have admin permissions, the callback is still called, but with an empty table.
+-- @param function callback Called with the decision table as the only argument.
+-- @realm shared
+roleinspect.GetDecisions = getDecisionsImpl

lua/terrortown/entities/roles/ttt_role_base/init.lua

@@ -24,6 +24,7 @@ function ROLE:RemoveRoleLoadout(ply, isRoleChange) end
 -- Checks whether a role is able to get selected (and maybe assigned to a @{Player}) if the round starts
 -- @param boolean avoidHook should the @{hook.TTT2RoleNotSelectable} hook be ignored?
 -- @return boolean
+-- @return ROLEINSPECT_REASON
 -- @realm server
 function ROLE:IsSelectable(avoidHook)
     if self == roles.INNOCENT or self == roles.TRAITOR then
@@ -42,6 +43,8 @@ function ROLE:IsSelectable(avoidHook)
         return false, ROLEINSPECT_REASON_NOT_ENABLED
     end
 
+    ---
+    -- @realm server
     if not avoidHook and hook.Run("TTT2RoleNotSelectable", self) then
         return false, ROLEINSPECT_REASON_NOT_SELECTABLE
     end