Added some structor concepts

utils/debug.lua

@@ -31,7 +31,7 @@ end
 
 ---Shows the given message if debug is enabled. Uses serpent to print non scalars.
 -- @param message <table|string|number|boolean>
--- @param stack_traceback <number|nil> levels of stack trace to give, defaults to 1 level if nil
+-- @param trace_levels <number|nil> levels of stack trace to give, defaults to 1 level if nil
 function Debug.print(message, trace_levels)
     if not _DEBUG then
         return

utils/math.lua

@@ -39,7 +39,8 @@ math.calculate_slope = function(x1, y1, x2, y2)
 end
 
 --- Calculates the y-intercept of a line
--- @param x, y numbers - coordinates of point on line
+-- @param x number - coordinates of point on line
+-- @param y number - coordinates of point on line
 -- @param slope number - the slope of a line
 -- @return number - the y-intercept of a line
 math.calculate_y_intercept = function(x, y, slope)

utils/state_machine.lua

@@ -87,8 +87,8 @@ end
 -- You may register multiple handlers for the same transition
 -- NOTICE: This function will invoke an error if called after init. Dynamic machine changes are currently unsupported
 -- @param self StateMachine the machine
--- @param state number/string exiting state
--- @param state number/string entering state
+-- @param old number/string exiting state
+-- @param new number/string entering state
 -- @param callback function
 function Module.register_transition_callback(self, old, new, callback)
     if _LIFECYCLE ~= control_stage then

utils/table.lua

@@ -49,7 +49,7 @@ end
 --- Checks if a table contains an element
 -- @param t <table>
 -- @param e <any> table element
--- @returns <any> the index of the element or nil
+-- @return <any> the index of the element or nil
 function table.index_of(t, e)
     for k, v in pairs(t) do
         if v == e then
@@ -62,7 +62,7 @@ end
 --- Checks if the arrayed portion of a table contains an element
 -- @param t <table>
 -- @param e <any> table element
--- @returns <number|nil> the index of the element or nil
+-- @return <number|nil> the index of the element or nil
 function table.index_of_in_array(t, e)
     for i = 1, #t do
         if t[i] == e then
@@ -76,7 +76,7 @@ local index_of = table.index_of
 --- Checks if a table contains an element
 -- @param t <table>
 -- @param e <any> table element
--- @returns <boolean> indicating success
+-- @return <boolean> indicating success
 function table.contains(t, e)
     return index_of(t, e) and true or false
 end
@@ -85,7 +85,7 @@ local index_of_in_array = table.index_of_in_array
 --- Checks if the arrayed portion of a table contains an element
 -- @param t <table>
 -- @param e <any> table element
--- @returns <boolean> indicating success
+-- @return <boolean> indicating success
 function table.array_contains(t, e)
     return index_of_in_array(t, e) and true or false
 end
@@ -128,11 +128,10 @@ end
 
 --- Chooses a random entry from a weighted table
 -- because this uses math.random, it cannot be used outside of events
--- @param weight_table <table> of tables with items and their weights
+-- @param weighted_table <table> of tables with items and their weights
 -- @param item_index <number> of the index of items, defaults to 1
 -- @param weight_index <number> of the index of the weights, defaults to 2
 -- @return <any> table element
--- @see features.chat_triggers::hodor
 function table.get_random_weighted(weighted_table, item_index, weight_index)
     local total_weight = 0
     item_index = item_index or 1
@@ -156,6 +155,7 @@ end
 -- because this uses math.random, it cannot be used outside of events if no rng is supplied
 -- from: http://www.sdknews.com/cross-platform/corona/tutorial-how-to-shuffle-table-items
 -- @param t <table> to shuffle
+-- @param rng <function> to provide random numbers
 function table.shuffle_table(t, rng)
     local rand = rng or math.random
     local iterations = #t