Document how the secondary view works

engine/User.lua

@@ -386,9 +386,17 @@ end
 function GetFireState(units)
 end
 
---- Returns the root UI frame for a given head
+--- Returns the root UI frame for a given adapter. You can use `GetFrame(0)` to retrieve the primary adapter. And you can use `GetFrame(1)` to retrieve the secondary adapter. 
+---
+--- In the game options you can add a second adapter under the 'Video' tab.
+--- 
+--- See also `GetNumRootFrames()` to determine the number of root frames. 
+--- 
+--- See also the following modules that manage these frames:
+--- - Primary adapter: lua\ui\game\worldview.lua
+--- - Secondary adapter: lua\ui\game\multihead.lua
 ---@param head number
----@return Frame
+---@return Frame | nil
 function GetFrame(head)
 end
 
@@ -473,7 +481,14 @@ end
 function GetMovieVolume()
 end
 
---- Returns the current number of root frames (typically one per head)
+--- Returns the current number of root frames. There is usually only one root frame for each adapter (monitor). This is often referred to as a 'head' in other comments.
+--- 
+--- In the game options you can add a second adapter under the 'Video' tab.
+---
+--- See also `GetFrame(0)` and `GetFrame(1)` to retrieve the root frame for a given adapter. 
+--- See also the following modules that manage these frames:
+--- - Primary adapter: lua\ui\game\worldview.lua
+--- - Secondary adapter: lua\ui\game\multihead.lua
 ---@return number
 function GetNumRootFrames()
 end

lua/ui/game/multihead.lua

@@ -12,19 +12,39 @@ local Group = import("/lua/maui/group.lua").Group
 local GameCommon = import("/lua/ui/game/gamecommon.lua")
 local Bitmap = import("/lua/maui/bitmap.lua").Bitmap
 
+---@type WorldView | false
 view = false
 
+--- Shows the logo in the secondary adapter.
+---@return nil
 function ShowLogoInHead1()
-    if GetNumRootFrames() < 2 then return end
+
+    ---------------------------------------------------------------------------
+    -- defensive programming
+
+    -- don't do anything if there's only one root frame
+    if GetNumRootFrames() < 2 then
+        return
+    end
 
     local rootFrame = GetFrame(1)
     local bg = Bitmap(rootFrame, UIUtil.UIFile('/marketing/splash.dds'))
     LayoutHelpers.FillParentPreserveAspectRatio(bg, rootFrame)
 end
 
+--- Creates a world view on the secondary adapter. The worldview is registered and available in the world view manager.
+---
+--- This function is referenced directly by the engine.
+---@return nil
 function CreateSecondView()
-    if GetNumRootFrames() < 2 then return end
-
+    ---------------------------------------------------------------------------
+    -- defensive programming
+
+    -- don't do anything if there's only one root frame
+    if GetNumRootFrames() < 2 then
+        return
+    end
+
     ClearFrame(1)
     secondHeadGroup = Group(GetFrame(1), "secondHeadGroup")
     LayoutHelpers.FillParent(secondHeadGroup, GetFrame(1))
@@ -34,4 +54,4 @@ function CreateSecondView()
     view:SetRenderPass(UIUtil.UIRP_UnderWorld | UIUtil.UIRP_PostGlow) -- don't change this or the camera will lag one frame behind
     LayoutHelpers.FillParent(view, secondHeadGroup)
 
-end
+end