diff --git a/modpol_core/interactions/interactions.lua b/modpol_core/interactions/interactions.lua index 37f05be..1581e78 100644 --- a/modpol_core/interactions/interactions.lua +++ b/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 --- 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.interactions.binary_poll_user +-- @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() diff --git a/modpol_core/modules/add_child_org_consent.lua b/modpol_core/modules/add_child_org_consent.lua index f98aebc..34d2c7f 100644 --- a/modpol_core/modules/add_child_org_consent.lua +++ b/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: ", diff --git a/modpol_core/modules/change_modules-dropdown.lua b/modpol_core/modules/change_modules-dropdown.lua index ae651ec..efeb3d9 100644 --- a/modpol_core/modules/change_modules-dropdown.lua +++ b/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 --- @field type "add" or "remove" +--- Propose a change. +-- 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 diff --git a/modpol_core/modules/change_modules.lua b/modpol_core/modules/change_modules.lua index b43e5b0..beec34d 100644 --- a/modpol_core/modules/change_modules.lua +++ b/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 = {} diff --git a/modpol_core/modules/consent.lua b/modpol_core/modules/consent.lua index bb1acfe..4311421 100644 --- a/modpol_core/modules/consent.lua +++ b/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 diff --git a/modpol_core/modules/create_token.lua b/modpol_core/modules/create_token.lua index 6f4c30c..e8becdd 100644 --- a/modpol_core/modules/create_token.lua +++ b/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 --- @param result (optional) Callback if this module is embedded in other modules --- @function initiate +--- Initiate function +-- @function create_toke: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 diff --git a/modpol_core/modules/defer_consent.lua b/modpol_core/modules/defer_consent.lua index b931bf8..60492bc 100644 --- a/modpol_core/modules/defer_consent.lua +++ b/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 --- @param result (optional) Callback if this module is embedded in other modules --- @function initiate +--- Initiate function +-- @param result Callback if this module is embedded in other modules +-- @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 diff --git a/modpol_core/modules/display_processes.lua b/modpol_core/modules/display_processes.lua index c851fc5..e2feb21 100644 --- a/modpol_core/modules/display_processes.lua +++ b/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 --- @param result (optional) Callback if this module is embedded in other modules --- @function initiate +--- Initiate function +-- @function display_processes: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 diff --git a/modpol_core/modules/join_org.lua b/modpol_core/modules/join_org.lua index 8405ac6..ae78a4e 100644 --- a/modpol_core/modules/join_org.lua +++ b/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, diff --git a/modpol_core/modules/join_org_consent.lua b/modpol_core/modules/join_org_consent.lua index 408aadc..79423f8 100644 --- a/modpol_core/modules/join_org_consent.lua +++ b/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( diff --git a/modpol_core/modules/leave_org.lua b/modpol_core/modules/leave_org.lua index 2ba71ee..60ef085 100644 --- a/modpol_core/modules/leave_org.lua +++ b/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( diff --git a/modpol_core/modules/message_org.lua b/modpol_core/modules/message_org.lua index 90f0263..a251e5f 100644 --- a/modpol_core/modules/message_org.lua +++ b/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: ", diff --git a/modpol_core/modules/randomizer.lua b/modpol_core/modules/randomizer.lua index fa45851..59061c1 100644 --- a/modpol_core/modules/randomizer.lua +++ b/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 diff --git a/modpol_core/modules/remove_child_consent.lua b/modpol_core/modules/remove_child_consent.lua index e598457..e2bceb9 100644 --- a/modpol_core/modules/remove_child_consent.lua +++ b/modpol_core/modules/remove_child_consent.lua @@ -1,5 +1,5 @@ ---- Remove child (consent) --- A simple module that calls a consent process on an org to remove its child +--- Remove child (consent). +-- 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, diff --git a/modpol_core/modules/remove_member_consent.lua b/modpol_core/modules/remove_member_consent.lua index 1e21072..8a5a4fe 100644 --- a/modpol_core/modules/remove_member_consent.lua +++ b/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, diff --git a/modpol_core/modules/remove_org.lua b/modpol_core/modules/remove_org.lua index f7fa5d7..eb217f8 100644 --- a/modpol_core/modules/remove_org.lua +++ b/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( diff --git a/modpol_core/modules/remove_org_consent.lua b/modpol_core/modules/remove_org_consent.lua index b241d7c..61ad4a2 100644 --- a/modpol_core/modules/remove_org_consent.lua +++ b/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, diff --git a/modpol_core/modules/remove_process.lua b/modpol_core/modules/remove_process.lua index b5c5339..13b12e2 100644 --- a/modpol_core/modules/remove_process.lua +++ b/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 --- @param result (optional) Callback if this module is embedded in other modules --- @function initiate +--- Initiate function +-- @function remove_process: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 diff --git a/modpol_core/modules/rename_org_consent.lua b/modpol_core/modules/rename_org_consent.lua index d5a3369..49629b1 100644 --- a/modpol_core/modules/rename_org_consent.lua +++ b/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: ", diff --git a/modpol_core/modules/send_token.lua b/modpol_core/modules/send_token.lua index 84e0019..98d629b 100644 --- a/modpol_core/modules/send_token.lua +++ b/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 --- @param result (optional) Callback if this module is embedded in other modules --- @function initiate +--- initiate function +-- @function send_token: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 diff --git a/modpol_core/modules/template.lua b/modpol_core/modules/template.lua index 4987740..3a4c531 100644 --- a/modpol_core/modules/template.lua +++ b/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 = { --
  • self.org (the org the module was called in),
  • --
  • self.initiator (the user that callced the module),
  • --
  • self.id (the process id of the module instance)
  • --- @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! diff --git a/modpol_core/modules/tokenomics.lua b/modpol_core/modules/tokenomics.lua index d9aa306..372fda7 100644 --- a/modpol_core/modules/tokenomics.lua +++ b/modpol_core/modules/tokenomics.lua @@ -1,6 +1,6 @@ ---- tokenomics --- @module tokenomics +--- 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 --- set up the token data structure --- create an org treasury +--- Initiate function: creates a token in an org. +-- Set up the token data structure. +-- 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 --- if no user, get treasury balance +--- Returns 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 diff --git a/modpol_core/orgs/process.lua b/modpol_core/orgs/process.lua index b20b280..aedaa36 100644 --- a/modpol_core/orgs/process.lua +++ b/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 diff --git a/modpol_minetest/overrides/interactions.lua b/modpol_minetest/overrides/interactions.lua index 69b3fe9..9bbca45 100644 --- a/modpol_minetest/overrides/interactions.lua +++ b/modpol_minetest/overrides/interactions.lua @@ -1,5 +1,4 @@ --- INTERACTIONS.LUA (for Minetest) - +--- INTERACTIONS.LUA (for Minetest) -- CONTEXTUAL STUFF -- ================