Ldoc comments for orgs.base and edited comments for template_module

This commit is contained in:
SkylarHew 2022-01-09 22:15:54 -07:00
parent 956f9a2635
commit 4052fa4b55
2 changed files with 62 additions and 46 deletions

View File

@ -1,11 +1,11 @@
--- module_template
--- Template for module writers
-- @module module_template
--- (Required): data table containing name and description of the module
--- (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"
-- @field hide Whether this is a hidden utility module
local module_template = {
name = "Module Human-Readable Name",
slug = "module_template",
@ -14,12 +14,12 @@ local module_template = {
}
--- (Required) Data for module
-- Variables that module uses during the course of a process
-- Variables that module uses during the course of a process.
-- Can be blank
module_template.data = {
}
--- (Required): config for module
--- (Required): Config for module
-- Defines the input parameters to the module initiate function.
-- Can be blank
-- When calling a module from within another module,
@ -32,7 +32,7 @@ module_template.config = {
field_2 = "majority"
}
--- (Required): initiate function
--- (Required): Initiate function
-- Modules have access to the following instance variables:
-- <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>

View File

@ -1,5 +1,5 @@
--- Orgs: Base
-- Basic functions for orgs
--- Basic function for orgs
-- @module modpol.orgs.base
modpol.orgs = modpol.orgs or
{
@ -23,8 +23,10 @@ function temp_org()
}
end
-- ==================================================
-- returns org when given its id or name
--- Return org when given its id or name
-- @function modpol.orgs.get_org
-- @param arg string for name of org or id of org
-- @return org specified by id or name
function modpol.orgs.get_org(arg)
if type(arg) == 'string' then
for id, org in ipairs(modpol.orgs.array) do
@ -38,8 +40,9 @@ function modpol.orgs.get_org(arg)
return nil
end
-- ===============================================
-- returns a table list of all org names
--- Return a table list of all org names
-- @function modpol.orgs.list_all
-- @return a table list of all org names
function modpol.orgs.list_all()
local org_table
for k, v in ipairs(modpol.orgs.array) do
@ -54,9 +57,10 @@ function modpol.orgs.list_all()
return org_table
end
-- Function: modpol.orgs.user_orgs(user)
-- input: user (string)
-- output: table of strings of org names
--- Return the orgs of a user
-- @function modpol.orgs.user_orgs
-- @param user string of user name
-- @return table of strings of org names
function modpol.orgs.user_orgs(user)
local all_orgs = modpol.orgs.list_all()
local user_orgs = {}
@ -69,8 +73,8 @@ function modpol.orgs.user_orgs(user)
return user_orgs
end
-- ===========================================
-- deletes all orgs except for the instance
--- Deletes all orgs except for the
-- @function modpol.orgs.reset
function modpol.orgs.reset()
for id, org in ipairs(modpol.orgs.array) do
if id > 1 then
@ -86,9 +90,9 @@ function modpol.orgs.reset()
modpol.orgs:record('Resetting all orgs', 'org_reset')
end
-- ===================================================
-- initializes the instance (root org)
--- Initializes the instance (root org)
-- can only be run once, as only one instance can exist
-- @function modpol.orgs.init_instance
function modpol.orgs.init_instance()
local error_msg
if modpol.orgs.array[1] then
@ -114,8 +118,8 @@ end
-- FUNCTIONS BEYOND HERE OPERATE ON ORG OBJECTS
-- =======================================================
-- records a log message to the modpol ledger
--- Records a log message to the modpol ledger
-- @function modpol.orgs:record
function modpol.orgs:record(msg, entry_type)
local entry = {
timestamp = '',
@ -148,10 +152,12 @@ function modpol.orgs:record(msg, entry_type)
modpol.store_data()
end
-- ==================================================
-- adds a new sub org to the org it is called on
-- input: name (string), user (string)
-- ex: instance:add_org('town hall')
--- Adds a new sub org to the org it is called on.
-- Ex: instance:add_org('town hall')
-- @function modpol.orgs:add_org
-- @param name (string) name of new org
-- @param user (string)
-- @return child org created
function modpol.orgs:add_org(name, user)
if self.id == nil then
modpol.ocutil.log('Error in ' .. self.name .. ':add_org -> add_org can only be called by another org')
@ -194,10 +200,10 @@ function modpol.orgs:add_org(name, user)
return child_org
end
-- ========================================
-- recursively deletes an org and its suborgs
-- leaves entry in modpol.orgs.array as a string "removed"
-- note: "reason" param was removed, can be added back
--- Recursively deletes an org and its suborgs
-- Leaves entry in modpol.orgs.array as a string "removed".
-- Note: "reason" param was removed, can be added back
-- @function modpol.orgs:delete
function modpol.orgs:delete()
if self.id == 1 then
modpol.ocutil.log('Error in ' .. self.name .. ':delete -> cannot delete instance')
@ -219,9 +225,10 @@ function modpol.orgs:delete()
end
-- ===========================================
-- internal function to get the index of a member name
--- Internal function to get the index of a member name
-- @function modpol.orgs:get_member_index
-- @param member
-- @return index of given member
function modpol.orgs:get_member_index(member)
for k, v in ipairs(self.members) do
if v == member then
@ -230,8 +237,9 @@ function modpol.orgs:get_member_index(member)
end
end
-- ===========================================
-- adds a user to an org
--- Adds a user to an org
-- @function modpol.orgs:add_member
-- @param user
function modpol.orgs:add_member(user)
for id, name in ipairs(self.members) do
if user == name then
@ -253,8 +261,9 @@ function modpol.orgs:add_member(user)
end
-- =======================================
-- removes a user from an org
--- Removes a user from an org
-- @function modpol.orgs:remove_member
-- @param user
function modpol.orgs:remove_member(user)
-- sets the array index to an empty string so that consecutive list is preserved
-- empty spots will get filled in by new members
@ -268,8 +277,10 @@ function modpol.orgs:remove_member(user)
self:record('Removed member ' .. user, 'del_member')
end
-- ===========================================
-- boolean check whether user is an org
--- Boolean check whether user is an org
-- @function modpol.orgs:has_member
-- @param user
-- @return true if user is in org, false if not
function modpol.orgs:has_member(user)
local user_index = self:get_member_index(user)
if user_index then
@ -279,9 +290,9 @@ function modpol.orgs:has_member(user)
end
end
-- ==================================
-- Function: modpol.orgs:list_members()
-- output: a table of the names (string) of members
---
-- @function modpol.orgs:list_members()
-- @return a table of the names (string) of members
function modpol.orgs:list_members()
local members = {}
for k, v in ipairs(self.members) do
@ -290,8 +301,9 @@ function modpol.orgs:list_members()
return members
end
-- ==============================
-- because member list uses lazy deletion, using #org.members will not show an accurate number
--- Because member list uses lazy deletion, using #org.members will not show an accurate number
-- @function modpol.orgs:get_member_count
-- @return numbers of members
function modpol.orgs:get_member_count()
local count = 0
for k, v in ipairs(self.members) do
@ -302,9 +314,13 @@ function modpol.orgs:get_member_count()
end
return count
end
-- ====================================
-- adds a new policy to the policy table
-- must define the policy type, process associated with it, and whether the request must be made by an org member
--- Adds a new policy to the policy table.
-- Must define the policy type, process associated with it, and whether the request must be made by an org member
-- @function modpol.orgs:set_policy
-- @param policy_type
-- @param process_type
-- @param must_be_member Boolean
function modpol.orgs:set_policy(policy_type, process_type, must_be_member)
local new_policy = {
process_type = process_type,