Fix warnings and improve doc

sharedstate.lua

@@ -1,5 +1,9 @@
 local sharedstate={}
-logging=require((...):gsub("(.)$", "%1.") .. 'logging')
+local logging=require((...):gsub("(.)$", "%1.") .. 'logging')
+
+-- function names
+local is_initialized, callback_value, set_value,
+get_value, resolve_key, resolve_index
 
 -- we're protecting internal variables here, i'm *that* scared of writing bad
 -- code again.
@@ -19,9 +23,9 @@ do
 	local state_map={}
 
 	--- Check if initialized
-	-- Check if a key is initialized
-	-- @param key key
-	-- @return true if initialized, else false
+	---Check if a key is initialized
+	---@param key string key
+	---@return true if initialized, else false
 	function is_initialized(key)
 		logging.trace('is_initialized', key)
 		return state_table[key] ~= nil
@@ -29,10 +33,10 @@ do
 
 
 	--- Internal; ensure key is initialized
-	--Properly initialize a key in all tables.
-	--already initialized
-	--@param key key name
-	--@return true if key has been initialized, false if exists
+	---Properly initialize a key in all tables.
+	---already initialized
+	---@param key string key name
+	---@return boolean if key has been initialized
 	local function init_key(key)
 		logging.trace('init_key', key)
 		if key == nil then
@@ -53,8 +57,8 @@ do
 	end
 
 	--- Run callback function
-	-- Run the callback function of the given key
-	-- @param key key
+	---Run the callback function of the given key
+	---@param key string Key
 	function callback_value(key)
 		logging.trace("callback_value", key)
 		local new_value=state_table[key]["value"]
@@ -68,9 +72,9 @@ do
 	--- Set value and run callback
 	-- Sets a value in the state table, initializing it if neede, and runs
 	-- the callback if it has been previously set
-	-- @param key key
-	-- @param value value
-	-- @param callback callback function
+	---@param key string key
+	---@param value any value
+	---@param callback? function callback function
 	function set_value(key, value, callback)
 		logging.trace("set_value", key, value, callback)
 		local initialized=init_key(key)
@@ -89,9 +93,9 @@ do
 	end
 
 	--- Get value
-	--Get a value from the state table
-	--@param key key
-	--@return value from state table if set, else nil
+	---Get a value from the state table
+	---@param key string key
+	---@return any value from state table if set, else nil
 	function get_value(key)
 		logging.trace("get_value", key)
 		if not is_initialized(key) then return nil end
@@ -99,18 +103,18 @@ do
 	end
 
 	--- Resolve key
-	--Resolve key of given index
-	--@param index index
-	--@return key
+	---Resolve key of given index
+	---@param index integer index
+	---@return any key
 	function resolve_key(index)
 		logging.trace("resolve_key", index)
 		return state_map[index]
 	end
 
 	--- Resolve index
-	--Resolve index of given key
-	--@param key key
-	--@return index
+	---Resolve index of given key
+	---@param key string key
+	---@return integer index
 	function resolve_index(key)
 		logging.trace("resolve_index", key)
 		return state_table[key]["index"]
@@ -118,31 +122,31 @@ do
 end
 
 ---Add an item to the shared state store.
---Adds an item to the shared state store, as well as initializes it with a
---value. This does not send a ping and should only be used during avatar
---initialization.
---@param key key name
---@param value initial value
---@param callback Callback function to run on value change
+---Adds an item to the shared state store, as well as initializes it with a
+---value. This does not send a ping and should only be used during avatar
+---initialization.
+---@param key string key name
+---@param value any initial value
+---@param callback function Callback function to run on value change
 function sharedstate.add(key, value, callback)
 	logging.trace("sharedstate.add", key, value, callback)
 	set_value(key, value, callback)
 end
 
 --- Internal; transfer value over network
--- Ping used to transfer a value over the network, should not be called
--- directly
--- @param index Index of key
--- @param value New value
+---Ping used to transfer a value over the network, should not be called
+---directly
+---@param index integer Index of key
+---@param value any New value
 function pings.sharedstate_transfer(index, value)
 	logging.trace("pings.sharedstate_transfer", index, value)
 	set_value(resolve_key(index), value)
 end
 
 --- Set shared value
--- Sets a shared value. This sends a ping to transfer it over the network.
--- @param key key name
--- @param value value
+---Sets a shared value. This sends a ping to transfer it over the network.
+---@param key string key name
+---@param value any value
 function sharedstate.set(key, value)
 	logging.trace("sharedstate.set", key, value)
 	if not is_initialized(key) then