Added uglify options to dist, added documentation. Added Jenkinsfile options to build a master branch dist

Jenkinsfile

@@ -4,17 +4,24 @@ pipeline {
     stages {
         stage('Build') {
             steps {
-                sh '/opt/squish/bin/squish --no-minify'
+                sh 'squish --uglify'
                 sh "ldoc ${env.WORKSPACE}"
             }
         }
-       stage('Deploy') {
+        stage('Deploy') {
             when {
-                tag 'release-*'
+                anyOf { tag 'release-*'; branch 'master' }
             }
 
             steps {
-                sh "python3 /opt/hoggit_releaser/releaser.py ${env.WORKSPACE} ${env.TAG_NAME}"
+                script {
+                    if (env.TAG_NAME && env.TAG_NAME =~ /release-/) {
+                        TAG = env.TAG_NAME
+                    } else {
+                        TAG = env.BRANCH_NAME
+                    }
+                }
+                sh "python3 /opt/hoggit_releaser/releaser.py ${env.WORKSPACE} ${TAG}"
             }
         }
     }

hoggit/communication.lua

@@ -1,36 +1,52 @@
+--- communication.lua
+-- Menu system for groups via the F10 comms menu and messaging groups
+
 HOGGIT.GroupCommandAdded = {}
+
+--- Adds a menu item for the specified Group
+-- @param group Group to get the command
+-- @param text Text for the menu option
+-- @param parent Parent menu item to attach this command to
 HOGGIT.GroupCommand = function(group, text, parent, handler)
-  if HOGGIT.GroupCommandAdded[tostring(group)] == nil then
-    log("No commands from group " .. group .. " yet. Initializing menu state")
-    HOGGIT.GroupCommandAdded[tostring(group)] = {}
-  end
-  if not HOGGIT.GroupCommandAdded[tostring(group)][text] then
-    log("Adding " .. text .. " to group: " .. tostring(group))
-    callback = try(handler, function(err) log("Error in group command" .. err) end)
-    missionCommands.addCommandForGroup( group, text, parent, callback)
-    HOGGIT.GroupCommandAdded[tostring(group)][text] = true
-  end
+    if HOGGIT.GroupCommandAdded[tostring(group)] == nil then
+        log("No commands from group " .. group .. " yet. Initializing menu state")
+        HOGGIT.GroupCommandAdded[tostring(group)] = {}
+    end
+    if not HOGGIT.GroupCommandAdded[tostring(group)][text] then
+        log("Adding " .. text .. " to group: " .. tostring(group))
+        callback = try(handler, function(err) log("Error in group command" .. err) end)
+        missionCommands.addCommandForGroup(group, text, parent, callback)
+        HOGGIT.GroupCommandAdded[tostring(group)][text] = true
+    end
 end
-HOGGIT.GroupMenuAdded={}
-HOGGIT.GroupMenu = function( groupId, text, parent )
-  if HOGGIT.GroupMenuAdded[tostring(groupId)] == nil then
-    log("No commands from groupId " .. groupId .. " yet. Initializing menu state")
-    HOGGIT.GroupMenuAdded[tostring(groupId)] = {}
-  end
-  if not HOGGIT.GroupMenuAdded[tostring(groupId)][text] then
-    log("Adding " .. text .. " to groupId: " .. tostring(groupId))
-    HOGGIT.GroupMenuAdded[tostring(groupId)][text] = missionCommands.addSubMenuForGroup( groupId, text, parent )
-  end
-  return HOGGIT.GroupMenuAdded[tostring(groupId)][text]
+HOGGIT.GroupMenuAdded = {}
+HOGGIT.GroupMenu = function(groupId, text, parent)
+    if HOGGIT.GroupMenuAdded[tostring(groupId)] == nil then
+        log("No commands from groupId " .. groupId .. " yet. Initializing menu state")
+        HOGGIT.GroupMenuAdded[tostring(groupId)] = {}
+    end
+    if not HOGGIT.GroupMenuAdded[tostring(groupId)][text] then
+        log("Adding " .. text .. " to groupId: " .. tostring(groupId))
+        HOGGIT.GroupMenuAdded[tostring(groupId)][text] = missionCommands.addSubMenuForGroup(groupId, text, parent)
+    end
+    return HOGGIT.GroupMenuAdded[tostring(groupId)][text]
 end
 
+--- Send a message to a specific group
+-- @param groupId ID of the group that should get this message
+-- @param text The text that is shown in the message
+-- @param displayTime Amount of time in seconds to show the message
+-- @param clear if True use the clearview message option which will get rid of the black background in the message area
 HOGGIT.MessageToGroup = function(groupId, text, displayTime, clear)
-  if not displayTime then displayTime = 10 end
-  if clear == nil then clear = false end
-  trigger.action.outTextForGroup( groupId, text, displayTime, clear)
+    if not displayTime then displayTime = 10 end
+    if clear == nil then clear = false end
+    trigger.action.outTextForGroup(groupId, text, displayTime, clear)
 end
 
-HOGGIT.MessageToAll = function( text, displayTime )
-  if not displayTime then displayTime = 10 end
-  trigger.action.outText( text, displayTime )
+--- Send a message to all players on the server
+-- @param text The text that is shown in the message
+-- @param displayTime Amount of time in seconds to show the message
+HOGGIT.MessageToAll = function(text, displayTime)
+    if not displayTime then displayTime = 10 end
+    trigger.action.outText(text, displayTime)
 end

hoggit/error_handling.lua

@@ -1,9 +1,16 @@
-HandleError = function(err)
+--- error_handling.lua
+-- Adds intelligence to the way scripting errors in DCS are handled.
+-- Must be included after hoggit.logging module
+
+local HandleError = function(err)
     log("Error in pcall: "  .. err)
     log(debug.traceback())
     return err
 end
-  
+
+--- Adds basic try/catch functionality
+-- @param func unsafe function to call
+-- @param catch the function to call if func fails
 try = function(func, catch)
     return function()
       local r, e = xpcall(func, HandleError)

hoggit/group.lua

@@ -1,4 +1,4 @@
--- Returns the location of the first unit in a given group.
+--- Returns the location of the first unit in a given group.
 -- If the group is nil, this function returns nil.
 -- @param grp The group you want coordinates for.
 -- @return Vec3 The group's first unit's coordinates, or nil if the group is nil
@@ -9,7 +9,7 @@ HOGGIT.groupCoords = function(grp)
   return nil
 end
 
--- Starts a smoke beacon at the specified group's location
+--- Starts a smoke beacon at the specified group's location
 -- @param grp The group to smoke. Will be placed on or near the first unit.
 -- @param smokeColor The trigger.smokeColor enum value to use. Defaults to White smoke
 HOGGIT.smokeAtGroup = function(grp, smokeColor)

hoggit/logging.lua

@@ -1,9 +1,15 @@
+--- Logging.lua
+-- Logging utility for HOGGIT framework
+
+-- Open a log file for use
 logFile = io.open(HOGGIT.log_base..[[\HOGGIT.log]], "w")
 
+--- Write a string to the logfile
+-- @param str The string to write to the log
 function log(str)
-  if str == nil then str = 'nil' end
-  if logFile then
-    logFile:write("HOGGIT --- " .. str .."\r\n")
-    logFile:flush()
-  end
+    if str == nil then str = 'nil' end
+    if logFile then
+        logFile:write("HOGGIT --- " .. str .."\r\n")
+        logFile:flush()
+    end
 end

hoggit/utils.lua

@@ -1,8 +1,18 @@
+--- utils.lua
+-- Uncategorized utilities that are used often enough to justify inclusion in the framework
+
+--- Given a table with indexes as keys (a list in any other language, thanks lua) returns a random element
+-- @param table A table with indexes as keys
+-- @return A random element from the table
 HOGGIT.randomInList = function(list)
   local idx = math.random(1, #list)
   return list[idx]
 end
 
+--- Filters out elements that do not return true when passed to the function "filter"
+-- @param t Table to iterate over
+-- @param filter Function that each element in table "t" will be passed into.
+-- @return New table with filtered elements only
 HOGGIT.filterTable = function(t, filter)
   local out = {}
   for k,v in pairs(t) do
@@ -11,6 +21,10 @@ HOGGIT.filterTable = function(t, filter)
   return out
 end
 
+--- Checks to see if value "elem" is contained in any value of table "list"
+-- @param list Table to check
+-- @param elem Value to look for in each table element
+-- @return True/False if "elem" was found in "list"
 HOGGIT.listContains = function(list, elem)
   for _, value in ipairs(list) do
     if value == elem then
@@ -21,13 +35,17 @@ HOGGIT.listContains = function(list, elem)
   return false
 end
 
+--- Takes a DCS Vec2 position and returns a string with the lat and long
+-- @param pos Vec2 from DCS engine
+-- @param decimal if true then return result in Decimal instead of Seconds
+-- @return The Lat/Long string
 HOGGIT.getLatLongString = function(pos, decimal)
     local lat, long = coord.LOtoLL(pos)
     if decimal == nil then decimal = false end
     return mist.tostringLL(lat, long, 3, decimal)
 end
 
--- Returns a textual smoke name based on the provided enum
+--- Returns a textual smoke name based on the provided enum
 -- @param a trigger.smokeColor enum
 -- @return the English word as a string representing the color of the smoke. i.e. trigger.smokeColor.Red returns "Red"
 HOGGIT.getSmokeName = function(smokeColor)
@@ -38,6 +56,11 @@ HOGGIT.getSmokeName = function(smokeColor)
   if smokeColor == trigger.smokeColor.Blue then return "Blue" end
 end
 
+
+--- Returns if Group object is alive.
+-- This will catch some of the edge cases that the more common functions miss.
+-- @param group Group
+-- @return True if Group is indeed, alive.  False otherwise.
 HOGGIT.GroupIsAlive = function(group)
     local grp = nil
     if type(group) == "string" then