diff --git a/modpol_core/interactions/interactions.lua b/modpol_core/interactions/interactions.lua index f3df03c..709b481 100644 --- a/modpol_core/interactions/interactions.lua +++ b/modpol_core/interactions/interactions.lua @@ -1,7 +1,7 @@ --- INTERACTIONS.LUA (CLI) - +--- INTERACTIONS.LUA (CLI). -- User interaction functions for Modular Politics -- Called by modpol.lua +-- @module modpol.interactions modpol.interactions = {} @@ -9,10 +9,11 @@ modpol.interactions = {} -- DASHBOARDS -- ========== --- Function: modpol.interactions.dashboard(user) --- Params: user (string) +--- Output: Display a menu of commands to the user +-- @function modpol.interactions.dashboard +-- @param user (string) + -- Q: Should this return a menu of commands relevant to the specific user? --- Output: Displays a menu of commands to the user -- TKTK currently just prints all of modpol---needs major improvement function modpol.interactions.dashboard(user) -- adds user to root org if not already in it @@ -59,10 +60,10 @@ function modpol.interactions.dashboard(user) end end - --- Function: modpol.interactions.org_dashboard --- Params: user (string), org_string (string or id) --- Output: Displays a menu of org-specific commands to the user +--- Output: Displays a menu of org-specific commands to the user +-- @function modpol.interactions.org_dashboard +-- @param user (string) +-- @param org_string (string or id) function modpol.interactions.org_dashboard(user, org_string) local org = modpol.orgs.get_org(org_string) if not org then return nil end @@ -169,28 +170,35 @@ end -- output: opens a dashboard for viewing/editing policy details -- TODO - --- Function: modpol.interactions.message --- input: user (string), message (string) --- output: prints message to CLI +--- Output: Prints message to CLI +-- @function modpol.interactions.message +-- @param user (string) +-- @param message (string) function modpol.interactions.message(user, message) print(user .. ": " .. message) end --- Function: modpol.interactions.text_query --- input: User (string), Query (string), func (function) --- func input: user input (string) --- output: Applies "func" to user input +--- Output: Applies "func" to user input. +-- Func input: user input (string) +-- @function modpol.interactions.text_query +-- @param user (string) +-- @param query (string) +-- @param func (function) function modpol.interactions.text_query(user, query, func) print(user .. ": " .. query) answer = io.read() func(answer) end --- Function: dropdown_query --- input: user (string), label (string), options (table of strings), func(choice) (function) --- func input: choice (string) --- output: calls func on choice +--- Output: Calls func on choice. +-- func input: choice (string) +-- @function modpol.interactions.dropdown_query +-- @param user (string) +-- @param label (string) +-- @param options (table of strings) +-- @param func (choice) (function) + + function modpol.interactions.dropdown_query(user, label, options, func) -- set up options local options_display = "" @@ -226,10 +234,12 @@ function modpol.interactions.dropdown_query(user, label, options, func) end end --- Function: modpol.binary_poll_user(user, question) --- Params: user (string), question (string), func (function) --- func input: user input (string: y/n) --- Output: Applies "func" to user input +--- Output: Applies "func" to user input. +-- Func input: user input (string: y/n) +-- @function modpol.binary_poll_user(user, question) +-- @param user (string) +-- @param question (string) +-- @param func (function) function modpol.interactions.binary_poll_user(user, question, func) local query = "Poll for " .. user .. " (y/n): ".. question local answer @@ -251,9 +261,12 @@ end -- COMPLEX INTERACTIONS -- ==================== --- Function: modpol.interactions.message_org --- input: initiator (string), org (number or string), message (string) --- output: broadcasts message to all org members +--- Output: broadcasts message to all org members +-- @function modpol.interactions.message_org +-- @param initiator (string) +-- @param org (number or string) +-- @param message (string) + function modpol.interactions.message_org(initiator, org, message) local this_org = modpol.orgs.get_org(org) local users = this_org:list_members() diff --git a/modpol_core/orgs/process.lua b/modpol_core/orgs/process.lua index 8961a1a..b49cb2e 100644 --- a/modpol_core/orgs/process.lua +++ b/modpol_core/orgs/process.lua @@ -1,5 +1,12 @@ --- Process functions for orgs +-- @module modpol.orgs.process +--- Call modules +-- @function modpol.orgs.call_module +-- @param module_slug Same as module name +-- @param intiator Initiator for module +-- @param config Config for module +-- @param result function modpol.orgs:call_module(module_slug, initiator, config, result) if not modpol.modules[module_slug] then modpol.ocutil.log('Error in ' .. self.name .. ':call_module -> module "' .. module_slug .. '" not found') @@ -53,10 +60,18 @@ function modpol.orgs:call_module(module_slug, initiator, config, result) return index end +--- Delete process by id +-- @function modpol.orgs:delete_process +-- @param id Id of process function modpol.orgs:delete_process(id) self.processes[id] = 'deleted' end +--- Add a new pending action +-- @function modpol.orgs:add_pending_action +-- @param process_id Process id +-- @param user User adding the action +-- @param callback function modpol.orgs:add_pending_action(process_id, user, callback) self.pending[user] = self.pending[user] or {} self.pending[user][process_id] = callback @@ -64,18 +79,29 @@ function modpol.orgs:add_pending_action(process_id, user, callback) user, "New pending action in org "..self.name) end +--- Remove a pending action +-- @function modpol.orgs:remove_pending_action +-- @param process_id Process id to be removed +-- @param user function modpol.orgs:remove_pending_action(process_id, user) if self.pending[user] then self.pending[user][process_id] = nil end end +--- Wipe all pending actions for process +-- @function modpol.orgs:wipe_pending_actions +-- @param process_id function modpol.orgs:wipe_pending_actions(process_id) for user in pairs(self.pending) do self.pending[user][process_id] = nil end end +--- Check if there are pending actions for user +-- @function modpol.orgs:has_pending_actions +-- @param user User +-- @return True if there are pending actions for a user, false if not function modpol.orgs:has_pending_actions(user) -- next() will return the next pair in a table -- if next() returns nil, the table is empty @@ -90,6 +116,10 @@ function modpol.orgs:has_pending_actions(user) end end +--- Interact a user with given process +-- @function modpol.orgs:interact +-- @param process_id +-- @param user function modpol.orgs:interact(process_id, user) local process = self.processes[process_id] if self.pending[user] then