Added LDoc comments for new files, ready to merge pt. 2

modpol_core/interactions/interactions.lua

@@ -256,8 +256,8 @@ function modpol.interactions.message(user, message)
    print(user .. ": " .. message)
 end
 
---- Function: modpol.interactions.message_user
+--- Gets and sends a message from one user to another
--- Gets and sends a message from one user to another
+-- @function modpol.interactions.message_user
 -- @param sender Name of user sending (string)
 -- @param recipient Name of user receiving (string)
 function modpol.interactions.message_user(sender, recipient)
@@ -268,8 +268,9 @@ function modpol.interactions.message_user(sender, recipient)
       sel.." [from "..sender.."]")
 end
 
---- Function: modpol.interactions.display
+
--- Displays complex data to a user
+--- Displays complex data to a user
+-- @function modpol.interactions.display
 -- @param user Name of target user (string)
 -- @param title Title of display (string)
 -- @param message Content of message (string or table of strings)
@@ -301,7 +302,7 @@ function modpol.interactions.display(user, title, message, completion)
 end
 
 
--- Applies "func" to user input
+--- Applies "func" to user input.
 -- Func input: user input (string)
 -- @function modpol.interactions.text_query
 -- @param User (string)
@@ -314,7 +315,7 @@ function modpol.interactions.text_query(user, query, func)
 end
 
 --- Output: Calls func on choice.
--- func input: choice (string)
+-- Func input: choice (string)
 -- @function modpol.interactions.dropdown_query
 -- @param user (string)
 -- @param label (string)
@@ -405,10 +406,12 @@ function modpol.interactions.checkbox_query(
 end
 
 
--- Function: modpol.interactions.binary_poll_user
+--- 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.interactions.binary_poll_user
--- 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
@@ -435,7 +438,6 @@ end
 -- @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/modules/add_child_org_consent.lua

@@ -16,7 +16,7 @@ add_child_org_consent.config = {
 
 --- Initiate consent for new child org
 -- @function add_child_org_consent:initiate(result)
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function add_child_org_consent:initiate(result)
    modpol.interactions.text_query(
       self.initiator,"Child org name: ",

modpol_core/modules/change_modules-dropdown.lua

@@ -16,6 +16,9 @@ change_modules.data = {
 change_modules.config = {
 }
 
+--- Change modules initiate
+-- @function change_modules:initiate
+-- @param result Callback if this module is embedded in other modules
 function change_modules:initiate(result)
    self.data.result = result
    -- Step 1: add or remove?
@@ -32,6 +35,8 @@ function change_modules:initiate(result)
    )
 end
 
+--- Add a new module
+-- @function change_modules:add_module
 function change_modules:add_module()
    -- prepare module options
    local available_modules = modpol.util.copy_table(modpol.modules)
@@ -78,6 +83,8 @@ function change_modules:add_module()
    )
 end
 
+--- Remove a module
+-- @function change_modules:remove_module
 function change_modules:remove_module()
    -- prepare module options
    local available_modules = {}
@@ -125,8 +132,11 @@ function change_modules:remove_module()
    )
 end
 
---- propose_change
+--- Propose a change.
--- @field type "add" or "remove"
+-- Type "add" or "remove"
+-- @function change_modules:propose_change
+-- @param type
+-- @param mod_text
 function change_modules:propose_change(type, mod_text)
    self:call_module(
       "consent",self.initiator,
@@ -165,5 +175,4 @@ function change_modules:propose_change(type, mod_text)
    self.org:delete_process(self.id)
 end
    
---- (Required) Add to module table
 modpol.modules.change_modules = change_modules

modpol_core/modules/change_modules.lua

@@ -22,6 +22,7 @@ change_modules.config = {
 --- Initiate change in modules.
 -- Either adds or removes module depending on user input
 -- @function change_modules:initiate
+-- @param result Callback if this module is embedded in other modules
 function change_modules:initiate(result)
    self.data.result = result
    self.data.add_modules = {}

modpol_core/modules/consent.lua

@@ -19,7 +19,7 @@ consent.config = {
 
 --- Initiate consent
 -- @function consent:initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function consent:initiate(result)
    self.data.result = result
    -- if org is empty, consent is given automatically

modpol_core/modules/create_token.lua

@@ -1,6 +1,6 @@
---- create_token
+--- Create token.
+-- Depends on tokenomics
 -- @module create_token
--- depends on tokenomics
 
 local create_token = {
     name = "Create a token (consent)",
@@ -9,9 +9,6 @@ local create_token = {
     hide = false;
 }
 
---- (Required) Data for module
--- Variables that module uses during the course of a process
--- Can be blank
 create_token.data = {
 }
 
@@ -19,9 +16,9 @@ create_token.config = {
    token_name = ""
 }
 
---- (Required): initiate function
+--- Initiate function
--- @param result (optional) Callback if this module is embedded in other modules
+-- @function create_toke:initiate
--- @function initiate
+-- @param result Callback if this module is embedded in other modules
 function create_token:initiate(result)
    modpol.interactions.text_query(
       self.initiator,
@@ -49,5 +46,4 @@ function create_token:initiate(result)
    )
 end
 
---- (Required) Add to module table
 modpol.modules.create_token = create_token

modpol_core/modules/defer_consent.lua

@@ -1,11 +1,6 @@
---- defer_consent
+--- Defer consent
 -- @module defer_consent
 
---- (Required): data table containing name and description of the module
--- @field name "Human-readable name (parens OK, no brackets)"
--- @field slug "Same as module class name"
--- @field desc "Description of the module"
--- @field hide "Whether this is a hidden utility module"
 local defer_consent = {
     name = "Defer consent",
     slug = "defer_consent",
@@ -13,13 +8,10 @@ local defer_consent = {
     hide = true;
 }
 
---- (Required) Data for module
--- Variables that module uses during the course of a process
--- Can be blank
 defer_consent.data = {
 }
 
---- (Required): config for module 
+--- Config for module 
 -- @field defer_org Name or ID of target org
 -- @field votes_required Threshold passed on to `consent`
 -- @field prompt String passed on to `consent`
@@ -29,9 +21,9 @@ defer_consent.config = {
     prompt = "Do you consent?"
 }
 
---- (Required): initiate function
+--- Initiate function
--- @param result (optional) Callback if this module is embedded in other modules
+-- @param result Callback if this module is embedded in other modules
--- @function initiate
+-- @function defer_consent:initiate
 function defer_consent:initiate(result)
    local defer_org = modpol.orgs.get_org(self.config.defer_org)
    if not defer_org then

modpol_core/modules/display_processes.lua

@@ -1,4 +1,4 @@
---- display_processes
+--- Display processes
 -- @module display_processes
 
 local display_processes = {
@@ -8,18 +8,15 @@ local display_processes = {
     hide = false;
 }
 
---- (Required) Data for module
--- Variables that module uses during the course of a process
--- Can be blank
 display_processes.data = {
 }
 
 display_processes.config = {
 }
 
---- (Required): initiate function
+--- Initiate function
--- @param result (optional) Callback if this module is embedded in other modules
+-- @function display_processes:initiate
--- @function initiate
+-- @param result Callback if this module is embedded in other modules
 function display_processes:initiate(result)
    local display_table = {}
    for k,v in pairs(self.org.processes) do
@@ -66,5 +63,4 @@ function display_processes:initiate(result)
    )
 end
 
---- (Required) Add to module table
 modpol.modules.display_processes = display_processes

modpol_core/modules/join_org.lua

@@ -11,7 +11,7 @@ join_org.setup = {
 
 --- Adds the user to the org
 -- @function join_org.initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function join_org.initiate(result) 
     modpol.interactions.binary_poll_user(
         initiator, 

modpol_core/modules/join_org_consent.lua

@@ -18,7 +18,7 @@ join_org_consent.config = {
 
 --- Initiate join org with consent
 -- @function join_org_consent:initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function join_org_consent:initiate(result)
    if self.org:has_member(self.initiator) then
       modpol.interactions.message(

modpol_core/modules/leave_org.lua

@@ -15,7 +15,7 @@ leave_org.config = {
 
 --- Removes user from org
 -- @function leave_org:initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function leave_org:initiate(result)
    if self.org == modpol.instance then
       modpol.interactions.message(

modpol_core/modules/message_org.lua

@@ -16,7 +16,7 @@ message_org.config = {
 
 --- Allows user to send input message to all org members
 -- @function initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function message_org:initiate(result)
    modpol.interactions.text_query(
       self.initiator, "Message to all org members: ",

modpol_core/modules/randomizer.lua

@@ -1,5 +1,5 @@
---- @module randomizer
+--- A utility module that outputs a random result from a set of options
--- A utility module that outputs a random result from a set of options
+-- @module randomizer
 
 local randomizer = {
     name = "Randomizer",
@@ -18,6 +18,9 @@ randomizer.config = {
     result_table = {}
 }
 
+--- Initiate function
+-- @function randomizer:initiate
+-- @param result Callback if this module is embedded in other modules
 function randomizer:initiate(result)
    self.data.result = result
    self.data.options_table = modpol.util.copy_table(self.config.options_table)
@@ -32,7 +35,8 @@ function randomizer:initiate(result)
    end
 end
 
--- returns result_table
+--- Returns result_table
+-- @function randomizer:random_loop
 function randomizer:random_loop()
    self.data.results = 0
    if results == self.config.num_results then

modpol_core/modules/remove_child_consent.lua

@@ -1,5 +1,5 @@
---- Remove child (consent)
+--- Remove child (consent).
--- A simple module that calls a consent process on an org to remove its child
+-- A simple module that calls a consent process on an org to remove its child.
 -- Depends on the Consent module.
 -- @module remove_child_consent
 
@@ -19,7 +19,7 @@ remove_child_consent.config = {
 
 --- Removes a child org with consent
 -- @function remove_child_consent:initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function remove_child_consent:initiate(result)
    local children = {}
    for i,v in ipairs(self.org.children) do
@@ -58,6 +58,8 @@ function remove_child_consent:initiate(result)
    end
 end
 
+--- Complete the remove process
+-- @function remove_child_consent:complete
 function remove_child_consent:complete()
    modpol.interactions.message_org(
       self.initiator, self.data.child_to_remove.id,

modpol_core/modules/remove_member_consent.lua

@@ -17,7 +17,7 @@ remove_member_consent.config = {
 
 --- Removes given member from org
 -- @function remove_member_consent:initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function remove_member_consent:initiate(result)
    -- Abort if in root org
    if self.org == modpol.instance then
@@ -52,6 +52,8 @@ function remove_member_consent:initiate(result)
    end
 end
 
+--- Complete after consent
+-- @function remove_member_consent:complete
 function remove_member_consent:complete()
    modpol.interactions.message_org(
       self.initiator, self.org.id,

modpol_core/modules/remove_org.lua

@@ -12,7 +12,7 @@ remove_org.data = {}
 
 --- Removes org
 -- @function remove_org:initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function remove_org:initiate(result)
    if self.org == modpol.instance then
    modpol.interactions.message(

modpol_core/modules/remove_org_consent.lua

@@ -18,7 +18,7 @@ remove_org_consent.config = {
 
 --- Remove org if all members consent
 -- @function remove_org_consent:initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function remove_org_consent:initiate(result)
    if self.org == modpol.instance then
       modpol.interactions.message(
@@ -44,6 +44,8 @@ function remove_org_consent:initiate(result)
    end
 end
 
+--- Complete after consent
+-- @function remove_org_consent:complete
 function remove_org_consent:complete()
    modpol.interactions.message_org(
       self.initiator, self.org.id,

modpol_core/modules/remove_process.lua

@@ -1,4 +1,4 @@
---- remove_process
+--- Remove a process
 -- @module remove_process
 
 local remove_process = {
@@ -8,18 +8,15 @@ local remove_process = {
     hide = false;
 }
 
---- (Required) Data for module
--- Variables that module uses during the course of a process
--- Can be blank
 remove_process.data = {
 }
 
 remove_process.config = {
 }
 
---- (Required): initiate function
+--- Initiate function
--- @param result (optional) Callback if this module is embedded in other modules
+-- @function remove_process:initiate
--- @function initiate
+-- @param result Callback if this module is embedded in other modules
 function remove_process:initiate(result)
    -- prepare process options
    local available_processes = {}
@@ -108,6 +105,4 @@ function remove_process:initiate(result)
    )
 end
 
-
---- (Required) Add to module table
 modpol.modules.remove_process = remove_process

modpol_core/modules/rename_org_consent.lua

@@ -19,7 +19,7 @@ rename_org_consent.config = {
 
 --- Renames the org after consent is reached
 -- @function rename_org_consent:initiate
--- @param result
+-- @param result Callback if this module is embedded in other modules
 function rename_org_consent:initiate(result)
    modpol.interactions.text_query(
       self.initiator,"New org name: ",

modpol_core/modules/send_token.lua

@@ -1,6 +1,6 @@
---- send_token
+--- Send token.
+-- Depends on tokenomics
 -- @module send_token
--- depends on tokenomics
 
 local send_token = {
     name = "Send tokens",
@@ -19,9 +19,9 @@ send_token.config = {
    token_name = ""
 }
 
---- (Required): initiate function
+--- initiate function
--- @param result (optional) Callback if this module is embedded in other modules
+-- @function send_token:initiate
--- @function initiate
+-- @param result Callback if this module is embedded in other modules
 function send_token:initiate(result)
    local token_list = {}
    if self.org.tokens then
@@ -73,5 +73,4 @@ function send_token:initiate(result)
    end
 end
 
---- (Required) Add to module table
 modpol.modules.send_token = send_token

modpol_core/modules/template.lua

@@ -1,4 +1,5 @@
---- Template for module writers
+--- Template for module writers.
+-- Short description goes here.
 -- @module module_template
 
 --- (Required): Data table containing name and description of the module
@@ -37,8 +38,8 @@ module_template.config = {
 -- <li><code>self.org</code> (the org the module was called in),</li>
 -- <li><code>self.initiator</code> (the user that callced the module),</li>
 -- <li><code>self.id</code> (the process id of the module instance)</li>
--- @param result (optional) Callback if this module is embedded in other modules
 -- @function module_template:initiate
+-- @param result (optional) Callback if this module is embedded in other modules
 function module_template:initiate(result)
    -- call interaction functions here!
 

modpol_core/modules/tokenomics.lua

@@ -1,6 +1,6 @@
---- tokenomics
+--- Tokenomics.
--- @module tokenomics
 -- Depends on consent
+-- @module tokenomics
 
 local tokenomics = {
     name = "Tokenomics",
@@ -9,14 +9,11 @@ local tokenomics = {
     hide = true;
 }
 
---- (Required) Data for module
--- Variables that module uses during the course of a process
--- Can be blank
 tokenomics.data = {
    result = nil
 }
 
---- (Required): config for module 
+--- Config for module 
 -- @field consent Require consent to create?
 -- @field token_variables the data that goes into the token
 -- @field token_slug A no-spaces slug for the token
@@ -33,11 +30,11 @@ tokenomics.config = {
    }
 }
 
---- (Required): initiate function: creates a token in an org
+--- Initiate function: creates a token in an org.
--- set up the token data structure
+-- Set up the token data structure.
--- create an org treasury
+-- Create an org treasury
+-- @function tokenomics:initiate
 -- @param result (optional) Callback if this module is embedded in other modules
--- @function initiate
 function tokenomics:initiate(result)
    -- TODO need to create a series of interactions to get the info from users
    self.data.result = result
@@ -69,6 +66,8 @@ function tokenomics:initiate(result)
    end
 end
 
+--- Create token
+-- @function tokenomics:create_token
 function tokenomics:create_token()
    if not self.org.tokens then self.org.tokens = {} end
    self.org.tokens[self.config.token_slug] =
@@ -89,8 +88,9 @@ end
 -- all need to write to persistent data
 -- amount can be positive or negative (except transfer)
 
--- returns balance
+--- Returns balance.
--- if no user, get treasury balance
+-- If no user, get treasury balance
+-- @function tokenomics.balance
 -- @param org Name (string) or id (num)
 -- @param token Slug (string)
 -- @param user Name (string)
@@ -112,8 +112,12 @@ function tokenomics.balance(org, token, user)
    end
 end
 
+--- Change balance
+-- @function tokenomics.change_balance
 -- @param org Org name (string) or id (number)
 -- @param token Token slug (string)
+-- @param user
+-- @param amount
 function tokenomics.change_balance(org, token, user, amount)
    local this_org = modpol.orgs.get_org(org)
    if not this_org then
@@ -139,6 +143,12 @@ function tokenomics.change_balance(org, token, user, amount)
    end
 end
 
+--- Transfer tokens from a sender to recipient
+-- @function tokenomics.transfer
+-- @param org
+-- @param token
+-- @param sender
+-- @param recipient
 -- @param amount Positive number
 function tokenomics.transfer(org, token, sender, recipient, amount)
    local sender_balance = tokenomics.balance(org, token, sender)
@@ -161,6 +171,11 @@ function tokenomics.transfer(org, token, sender, recipient, amount)
    end
 end
 
+--- Transfer from treasury
+-- @function tokenomics.treasury_transfer
+-- @param org
+-- @param token
+-- @param recipient
 -- @param amount Can be positive or negative, assumes flow from treasury to recipient
 function tokenomics.treasury_transfer(org, token, recipient, amount)
    local this_org = modpol.orgs.get_org(org)
@@ -189,7 +204,11 @@ function tokenomics.treasury_transfer(org, token, recipient, amount)
    end
 end
 
--- creates new tokens in the org treasury
+--- Creates new tokens in the org treasury
+-- @function tokenomics.issue
+-- @param org
+-- @param token
+-- @param amount
 function tokenomics.issue(org, token, amount)
    local this_org = modpol.orgs.get_org(org)
    if not this_org then
@@ -209,5 +228,4 @@ end
 
 ------------------------------------------
 
---- (Required) Add to module table
 modpol.modules.tokenomics = tokenomics

modpol_core/orgs/process.lua

@@ -55,7 +55,10 @@ function modpol.orgs:call_module(module_slug, initiator, config, result, parent_
     return index
 end
 
-
+--- Get the root process of the given id
+-- @function modpol.orgs.get_root_process
+-- @param id
+-- @return root process
 function modpol.orgs:get_root_process(id)
     local process = self.processes[id]
     while (process.parent_id) do
@@ -64,6 +67,9 @@ function modpol.orgs:get_root_process(id)
     return process
 end
 
+--- Delete the process given id
+-- @function modpol.orgs.delete_process
+-- @param id
 function modpol.orgs:delete_process(id)
     local process = self.processes[id]
     if process and process ~= "deleted" then

modpol_minetest/overrides/interactions.lua

@@ -1,5 +1,4 @@
--- INTERACTIONS.LUA (for Minetest)
+--- INTERACTIONS.LUA (for Minetest)
-
 -- CONTEXTUAL STUFF
 -- ================