From 0189253b2cdb70d66440d7049240dd447cd3b8e9 Mon Sep 17 00:00:00 2001
From: Cooldude2606 <cooldude260607@gmail.com>
Date: Sat, 4 May 2019 16:27:54 +0100
Subject: [PATCH] Added Comments

---
 expcore/store.lua | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/expcore/store.lua b/expcore/store.lua
index 83ed9299..2c17d1da 100644
--- a/expcore/store.lua
+++ b/expcore/store.lua
@@ -19,6 +19,7 @@ Global.register(Store.data,function(tbl)
     Store.data = table
 end)
 
+--- Returns a factorio object for the sub_location
 local function get_sub_location_object(store_type,sub_location)
     if store_type == Store.types.player then
         sub_location = Game.get_player_from_any(sub_location)
@@ -35,10 +36,17 @@ local function get_sub_location_object(store_type,sub_location)
     end
 end
 
+--- Emits an event to the external store that a value was updated
 local function set_global_location_value(location,sub_location,value)
     -- not yet impimented, this will emit to a file in some way to set the value in an external database
 end
 
+--- Register a new location to store a value, the valu returned from getter will be watched for updates
+-- @tparam location string the location path for the data must be unqiue
+-- @tparam store_type string the type of store this is, see Store.types
+-- @tparam getter function will be called to get the value for the store, the value is watched for updates
+-- @tparam setter function when the store value changes the setter will be called
+-- @tparam[opt=false] no_error boolean when true will skip check for location already registered
 function Store.register(location,store_type,getter,setter,no_error)
     if not no_error and Store.locations[location] then
         return error('The location is already registed: '..location,2)
@@ -52,6 +60,10 @@ function Store.register(location,store_type,getter,setter,no_error)
     }
 end
 
+--- Sets the stored values at the location, will call the setter function
+-- @tparam location string the location to be updated, must be registed
+-- @tparam sub_location string sub_location to set, either string,player,force or surface depending on store type
+-- @tparam value any the value to set at the location
 function Store.set(location,sub_location,value)
     if not Store.locations[location] then
         return error('The location is not registed: '..location)
@@ -68,6 +80,10 @@ function Store.set(location,sub_location,value)
     location.setter(sub_location_object or sub_location,value)
 end
 
+--- Gets the value at the location, if the value is nil then the getter function is called
+-- @tparam location string the location to be returned, must be registed
+-- @tparam sub_location string sub_location to get, either string,player,force or surface depending on store type
+-- @treturn any the value that was at this location
 function Store.get(location,sub_location)
     if not Store.locations[location] then return end
     location = Store.locations[location]
@@ -77,6 +93,10 @@ function Store.get(location,sub_location)
     return rtn
 end
 
+--- Checks if the store value needs updating, and if true will update it calling the setter function
+-- @tparam location string the location to be check, must be registed
+-- @tparam sub_location string sub_location to check, either string,player,force or surface depending on store type
+-- @treturn boolean if the value was updated and setter function called
 function Store.check(location,sub_location)
     if not Store.locations[location] then return false end
     location = Store.locations[location]
@@ -91,6 +111,7 @@ function Store.check(location,sub_location)
     return false
 end
 
+--- Checks once per second for changes to the store values
 Event.on_nth_tick(60,function()
     for _,location in pairs(Store.locations) do
         if location.store_type ~= Store.types['local'] then