Adds documentation for OO recipients and operator functions

scripts/lua/modules/alerts_api.lua

@@ -540,6 +540,10 @@ function alerts_api.checkThresholdAlert(params, alert_type, value)
      threshold_config.threshold
   )
 
+  -- Retrieve the function to be used for the threshold check.
+  -- The function depends on the operator, i.e., "gt", or "lt".
+  -- When there's no operator, the default "gt" function is taken from the available
+  -- operation functions
   local op_fn = user_scripts.operator_functions[threshold_config.operator] or user_scripts.operator_functions.gt
   if op_fn and op_fn(value, threshold_config.threshold) then alarmed = true end
 

scripts/lua/modules/recipients/base_recipients.lua

@@ -35,29 +35,41 @@ end
 
 -- ##############################################
 
+-- @brief Performs initialization operations at the time when the instance is created
 function base_recipients:_initialize()
+   -- Possibly create a default recipient (if not existing)
 end
 
 -- ##############################################
 
+-- @brief Dispatches a store `notification` to the recipient
+-- @param notification A JSON string with all the alert information
+-- @return true If the dispatching has been successfull, false otherwise
 function base_recipients:dispatch_store_notification(notification)
    return true
 end
 
 -- ##############################################
 
+-- @brief Dispatches a trigger `notification` to the recipient
+-- @param notification A JSON string with all the alert information
+-- @return true If the dispatching has been successfull, false otherwise
 function base_recipients:dispatch_trigger_notification(notification)
    return true
 end
 
 -- ##############################################
 
+-- @brief Dispatches a release `notification` to the recipient
+-- @param notification A JSON string with all the alert information
+-- @return true If the dispatching has been successfull, false otherwise
 function base_recipients:dispatch_release_notification(notification)
    return true
 end
 
 -- ##############################################
 
+-- @brief Process notifications previously dispatched with one of the dispatch_{store,trigger,release}_notification
 function base_recipients:process_notifications()
    return true
 end

scripts/lua/modules/recipients/recipients_lua_utils.lua

@@ -46,6 +46,7 @@ end
 
 local all_instances_cache
 
+-- @brief Caches all available recipient instances to avoid reloading them every time
 local function get_all_instances_cache()
    if not all_instances_cache then
       all_instances_cache = all_recipient_instances_factory()
@@ -56,6 +57,9 @@ end
 
 -- ##############################################
 
+-- @brief Dispatches a trigger `notification` to every available recipient (trigger notifications are generated in `alerts_api.trigger`)
+-- @param notification A JSON string with all the alert information
+-- @return true If the dispatching has been successfull, false otherwise
 function recipients_lua_utils.dispatch_trigger_notification(notification)
    local all_instances = get_all_instances_cache()
 
@@ -68,6 +72,9 @@ end
 
 -- ##############################################
 
+-- @brief Dispatches a release `notification` to every available recipient (trigger notifications are generated in `alerts_api.release`)
+-- @param notification A JSON string with all the alert information
+-- @return true If the dispatching has been successfull, false otherwise
 function recipients_lua_utils.dispatch_release_notification(notification)
    local all_instances = get_all_instances_cache()
 
@@ -80,6 +87,9 @@ end
 
 -- ##############################################
 
+-- @brief Dispatches a store `notification` to every available recipient (trigger notifications are generated in `alerts_api.store`)
+-- @param notification A JSON string with all the alert information
+-- @return true If the dispatching has been successfull, false otherwise
 function recipients_lua_utils.dispatch_store_notification(notification)
    local all_instances = get_all_instances_cache()
 
@@ -92,6 +102,7 @@ end
 
 -- ##############################################
 
+-- @brief Processs notifications previously dispatched for every available recipient
 function recipients_lua_utils.process_notifications(notification)
    local all_instances = get_all_instances_cache()
 

scripts/lua/modules/user_scripts.lua

@@ -36,6 +36,10 @@ user_scripts.field_units = {
 
 -- ##############################################
 
+-- Operator functions associated to user scripts `operator`, which is specified
+-- both inside user scripts default configuration values, as well as when user scripts
+-- are configured from the UI.
+-- 
 user_scripts.operator_functions = {
    gt --[[ greater than --]] = function(value, threshold) return value > threshold end,
    lt --[[ less than    --]] = function(value, threshold) return value < threshold end,