Ldoc comments for orgs.base and edited comments for template_module

modpol_core/modules/template.lua

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

modpol_core/orgs/base.lua

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