Added Ldoc comments for interactions and orgs.process.lua

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)
+--- Output: Display a menu of commands to the user
--- Params: user (string)
+-- @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
 
-
+--- Output: Displays a menu of org-specific commands to the user
--- Function: modpol.interactions.org_dashboard
+-- @function modpol.interactions.org_dashboard
--- Params: user (string), org_string (string or id)
+-- @param user (string)
--- Output: Displays a menu of org-specific commands to the user
+-- @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
 
-
+--- Output: Prints message to CLI
--- Function: modpol.interactions.message
+-- @function modpol.interactions.message
--- input: user (string), message (string)
+-- @param user (string)
--- output: prints message to CLI
+-- @param message (string)
 function modpol.interactions.message(user, message)
    print(user .. ": " .. message)
 end
 
--- Function: modpol.interactions.text_query
+--- Output: Applies "func" to user input.
--- input: User (string), Query (string), func (function)
+-- Func input: user input (string)
---   func input: user input (string)
+-- @function modpol.interactions.text_query
--- output: Applies "func" to user input
+-- @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
+--- Output: Calls func on choice.
--- input: user (string), label (string), options (table of strings), func(choice) (function)
 -- func input: choice (string)
--- output: calls func on choice
+-- @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)
+--- Output: Applies "func" to user input.
--- Params: user (string), question (string), func (function)
+-- Func input: user input (string: y/n)
---   func input: user input (string: y/n)
+-- @function modpol.binary_poll_user(user, question)
--- Output: Applies "func" to user input
+-- @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
+--- Output: broadcasts message to all org members
--- input: initiator (string), org (number or string), message (string)
+-- @function modpol.interactions.message_org
--- output: broadcasts message to all org members
+-- @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()

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