Cleaned core gui files

expcore/gui/top_flow.lua

@@ -1,5 +1,5 @@
 --[[-- Core Module - Gui
-- Used to define new gui elements and gui event handlers
+- Controls the elements on the top flow
 @module Gui
 ]]
 
@@ -12,7 +12,7 @@ local show_top_flow = Gui.core_defines.show_top_flow.name
 --- Top Flow.
 -- @section topFlow
 
---- Contains the uids of the elements that will show on the top flow and the auth function
+--- Contains the uids of the elements that will shown on the top flow and their auth functions
 -- @table top_elements
 Gui.top_elements = {}
 
@@ -20,29 +20,30 @@ Gui.top_elements = {}
 -- @field Gui.top_flow_button_style
 Gui.top_flow_button_style = mod_gui.button_style
 
---- The style that should be used for buttons on the top flow where the flow it opens is visible
+--- The style that should be used for buttons on the top flow when their flow is visible
 -- @field Gui.top_flow_button_visible_style
 Gui.top_flow_button_visible_style = 'menu_button_continue'
 
---[[-- Gets the flow which contains the elements for the top flow
+--[[-- Gets the flow refered to as the top flow, each player has one top flow
 @function Gui.get_top_flow(player)
 @tparam LuaPlayer player the player that you want to get the flow for
 @treturn LuaGuiElement the top element flow
 
-@usage-- Geting your top element flow
+@usage-- Geting your top flow
 local top_flow = Gui.get_top_flow(game.player)
 
 ]]
 Gui.get_top_flow = mod_gui.get_button_flow
 
---[[-- Adds an element to be drawn to the top flow when a player joins
-@tparam[opt] function authenticator called during toggle or update to decide if the element should be visible
-@treturn table the new element define that is used to register events to this element
+--[[-- Sets an element define to be drawn to the top flow when a player joins, includes optional authenticator
+@tparam[opt] function authenticator called during toggle or update to decide weather the element should be visible
+@treturn table the new element define to allow event handlers to be registered
 
-@usage-- Adding the example button
+@usage-- Adding an element to the top flow on join
 example_button:add_to_top_flow(function(player)
-    -- example button will only show when game time is less than 1 minute
-    return player.online_time < 3600
+    -- example button will only be shown if the player is an admin
+    -- note button will not update its state when player.admin is changed Gui.update_top_flow must be called for this
+    return player.admin
 end)
 
 ]]
@@ -51,10 +52,10 @@ function Gui._prototype_element:add_to_top_flow(authenticator)
     return self
 end
 
---[[-- Updates the visible states of all the elements on a players top flow
-@tparam LuaPlayer player the player that you want to update the flow for
+--[[-- Updates the visible state of all the elements on the players top flow, uses authenticator
+@tparam LuaPlayer player the player that you want to update the top flow for
 
-@usage-- Update your flow
+@usage-- Update your top flow
 Gui.update_top_flow(game.player)
 
 ]]
@@ -64,7 +65,7 @@ function Gui.update_top_flow(player)
     local is_visible = hide_button.visible
 
     -- Set the visible state of all elements in the flow
-    for name,authenticator in pairs(Gui.top_elements) do
+    for name, authenticator in pairs(Gui.top_elements) do
         -- Ensure the element exists
         local element = top_flow[name]
         if not element then
@@ -76,9 +77,9 @@ function Gui.update_top_flow(player)
     end
 end
 
---[[-- Toggles the visible states of all the elements on a players top flow
-@tparam LuaPlayer player the player that you want to toggle the flow for
-@tparam[opt] boolean state if given then the state will be set to this state
+--[[-- Toggles the visible state of all the elements on a players top flow, effects all elements
+@tparam LuaPlayer player the player that you want to toggle the top flow for
+@tparam[opt] boolean state if given then the state will be set to this
 @treturn boolean the new visible state of the top flow
 
 @usage-- Toggle your flow