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

This commit is contained in:
SkylarHew 2022-01-23 18:21:23 -07:00
parent e72911c67c
commit 79b548f9a0
24 changed files with 118 additions and 94 deletions

View File

@ -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()

View File

@ -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: ",

View File

@ -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

View File

@ -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 = {}

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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,

View File

@ -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(

View File

@ -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(

View File

@ -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: ",

View File

@ -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

View File

@ -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,

View File

@ -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,

View File

@ -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(

View File

@ -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,

View File

@ -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

View File

@ -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: ",

View File

@ -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

View File

@ -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!

View File

@ -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

View File

@ -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

View File

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